{"openapi":"3.1.0","info":{"title":"Conversa Labs","description":"REST API reference for Conversa Labs.","version":"4.15.1","contact":{"name":"Conversa Labs","url":"https://conversalabs.com.br"},"termsOfService":"https://conversalabs.com.br"},"servers":[{"url":"https://app.conversalabs.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":"Feature flags to enable/disable on the new account (operator currency). Flags marked `super_admin_only`, including Dashboard Apps native surfaces, are rejected and can be changed only from Super Admin.","properties":{"account_brain":{"type":"boolean","description":"Enables the Account Brain feature.","default":false},"ads_conversion_tracking":{"type":"boolean","description":"Enables the Ad Conversion Tracking (Meta CAPI) feature.","default":false},"ads_manager":{"type":"boolean","description":"Enables the Ads Manager feature.","default":false},"advanced_assignment":{"type":"boolean","description":"Enables the Advanced Assignment feature.","default":false},"advanced_search":{"type":"boolean","description":"Enables the Advanced Search feature.","default":false},"advanced_search_indexing":{"type":"boolean","description":"Enables the Advanced Search Indexing feature.","default":false},"affiliate_program":{"type":"boolean","description":"Enables the Affiliate Program feature.","default":false},"agent_bots":{"type":"boolean","description":"Enables the Agent Bots feature.","default":true},"agent_management":{"type":"boolean","description":"Enables the Agent Management feature.","default":true},"ai_onboarding":{"type":"boolean","description":"Enables the AI Onboarding (Generative Setup) feature.","default":false},"assignment_v2":{"type":"boolean","description":"Enables the Assignment V2 feature.","default":true},"audit_logs":{"type":"boolean","description":"Enables the Audit Logs feature.","default":false},"auto_resolve_conversations":{"type":"boolean","description":"Enables the Auto Resolve Conversations feature.","default":true},"automations":{"type":"boolean","description":"Enables the Automations feature.","default":true},"bug_reports":{"type":"boolean","description":"Enables the Bug Reports feature.","default":true},"calendar":{"type":"boolean","description":"Enables the Calendar feature.","default":false},"campaigns":{"type":"boolean","description":"Enables the Campaigns feature.","default":true},"canned_responses":{"type":"boolean","description":"Enables the Canned Responses feature.","default":true},"captain_document_auto_sync":{"type":"boolean","description":"Enables the Captain Document Auto Sync feature.","default":false},"captain_integration":{"type":"boolean","description":"Enables the Captain feature.","default":false},"captain_integration_v2":{"type":"boolean","description":"Enables the Captain V2 feature.","default":false},"captain_tasks":{"type":"boolean","description":"Enables the Captain Tasks feature.","default":false},"captain_v1_action_classifier":{"type":"boolean","description":"Enables the Captain V1 Action Classifier feature.","default":false},"catalog":{"type":"boolean","description":"Enables the Product Catalog feature.","default":true},"channel_email":{"type":"boolean","description":"Enables the Email Channel feature.","default":true},"channel_facebook":{"type":"boolean","description":"Enables the Facebook Channel feature.","default":true},"channel_instagram":{"type":"boolean","description":"Enables the Instagram Channel feature.","default":true},"channel_tiktok":{"type":"boolean","description":"Enables the TikTok Channel feature.","default":true},"channel_voice":{"type":"boolean","description":"Enables the Voice Channel feature.","default":false},"channel_website":{"type":"boolean","description":"Enables the Website Channel feature.","default":true},"chatwoot_v4":{"type":"boolean","description":"Enables the Chatwoot V4 feature.","default":true},"commerce_recovery":{"type":"boolean","description":"Enables the Commerce Recovery (Sales Recovery) feature.","default":false},"companies":{"type":"boolean","description":"Enables the Companies feature.","default":false},"contact_chatwoot_support_team":{"type":"boolean","description":"Enables the Contact Chatwoot Support Team feature.","default":true},"contracts":{"type":"boolean","description":"Enables the Contracts \u0026 E-signature feature.","default":false},"conversation_glance_signals":{"type":"boolean","description":"Enables the Conversation Glance Signals feature.","default":false},"conversation_required_attributes":{"type":"boolean","description":"Enables the Required Conversation Attributes feature.","default":false},"conversation_unread_counts":{"type":"boolean","description":"Enables the Conversation Unread Counts feature.","default":true},"crm":{"type":"boolean","description":"Enables the CRM feature.","default":true},"crm_integration":{"type":"boolean","description":"Enables the CRM Integration feature.","default":false},"crm_pipelines":{"type":"boolean","description":"Enables the CRM Pipelines feature.","default":true},"crm_v2":{"type":"boolean","description":"Enables the CRM V2 feature.","default":false},"csat_review_notes":{"type":"boolean","description":"Enables the CSAT Review Notes feature.","default":false},"custom_attributes":{"type":"boolean","description":"Enables the Custom Attributes feature.","default":true},"custom_reply_domain":{"type":"boolean","description":"Enables the Custom Reply Domain feature.","default":false},"custom_reply_email":{"type":"boolean","description":"Enables the Custom Reply Email feature.","default":false},"custom_roles":{"type":"boolean","description":"Enables the Custom Roles feature.","default":false},"custom_tools":{"type":"boolean","description":"Enables the Custom Tools feature.","default":false},"dashboard_apps_native_surfaces":{"type":"boolean","description":"Enables the Dashboard Apps Native Surfaces feature.","default":false},"disable_branding":{"type":"boolean","description":"Enables the Disable Branding feature. Deprecated flag, kept for backwards compatibility.","default":false},"email_continuity_on_api_channel":{"type":"boolean","description":"Enables the Email Continuity on API Channel feature.","default":false},"engagement_tracking":{"type":"boolean","description":"Enables the Engagement \u0026 Lead Score feature.","default":false},"field_level_permissions":{"type":"boolean","description":"Enables the Field-level Permissions feature.","default":true},"flow_builder":{"type":"boolean","description":"Enables the Flow Builder feature.","default":false},"flow_builder_runtime_v2":{"type":"boolean","description":"Enables the Flow Builder Runtime V2 feature.","default":false},"follow_ups":{"type":"boolean","description":"Enables the Follow-up feature.","default":false},"governance_lgpd":{"type":"boolean","description":"Enables the Governance \u0026 LGPD feature.","default":false},"granular_permissions":{"type":"boolean","description":"Enables the Granular Permissions feature.","default":true},"growth_ads":{"type":"boolean","description":"Enables the Growth Ads (CTWA \u0026 Lead Ads) feature.","default":false},"growth_social":{"type":"boolean","description":"Enables the Growth Social (Comment-to-DM) feature.","default":false},"growth_social_automation":{"type":"boolean","description":"Enables the Growth Social Automation (IG/TikTok/YouTube) feature.","default":false},"guided_tours":{"type":"boolean","description":"Enables the Guided Tours feature.","default":false},"help_center":{"type":"boolean","description":"Enables the Help Center feature.","default":true},"help_center_embedding_search":{"type":"boolean","description":"Enables the Help Center Embedding Search feature.","default":false},"inbound_emails":{"type":"boolean","description":"Enables the Inbound Emails feature.","default":true},"inbox_management":{"type":"boolean","description":"Enables the Inbox Management feature.","default":true},"inbox_view":{"type":"boolean","description":"Enables the Inbox View feature.","default":false},"insert_article_in_reply":{"type":"boolean","description":"Enables the Insert Article in Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"integrations":{"type":"boolean","description":"Enables the Integrations feature.","default":true},"internal_chat":{"type":"boolean","description":"Enables the Internal Chat feature.","default":false},"ip_lookup":{"type":"boolean","description":"Enables the IP Lookup feature.","default":false},"labels":{"type":"boolean","description":"Enables the Labels feature.","default":true},"launch_group_distribution":{"type":"boolean","description":"Enables the Launch Group Distribution feature.","default":false},"linear_integration":{"type":"boolean","description":"Enables the Linear Integration feature.","default":false},"macros":{"type":"boolean","description":"Enables the Macros feature.","default":true},"maestro_byok":{"type":"boolean","description":"Enables the Maestro BYOK (Account LLM Keys) feature.","default":true},"maestro_global_keys":{"type":"boolean","description":"Enables the Maestro Installation LLM Keys (Global Fallback) feature.","default":false},"mcp":{"type":"boolean","description":"Enables the MCP (Model Context Protocol) feature.","default":false},"media_library":{"type":"boolean","description":"Enables the Media Library feature.","default":true},"message_reply_to":{"type":"boolean","description":"Enables the Message Reply To feature. Deprecated flag, kept for backwards compatibility.","default":false},"message_scheduling":{"type":"boolean","description":"Enables the Message Scheduling feature.","default":false},"native_advanced_search":{"type":"boolean","description":"Enables the Advanced Search (Native) feature.","default":false},"native_audit_trail":{"type":"boolean","description":"Enables the Audit Trail (Native) feature.","default":false},"native_event_pipeline_v2":{"type":"boolean","description":"Enables the Native Event Pipeline V2 feature.","default":false},"notion_integration":{"type":"boolean","description":"Enables the Notion Integration feature.","default":false},"orders_registry":{"type":"boolean","description":"Enables the CRM Orders Registry feature.","default":false},"organizations":{"type":"boolean","description":"Enables the Organizations (Companies \u0026 Relationships) feature.","default":false},"outbound_agent_name_header":{"type":"boolean","description":"Enables the Outbound Agent Name Header feature.","default":false},"payments":{"type":"boolean","description":"Enables the Payments feature.","default":false},"platform_governance":{"type":"boolean","description":"Enables the Platform Governance feature.","default":true},"quoted_email_reply":{"type":"boolean","description":"Enables the Quoted Email Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"realtime_translation":{"type":"boolean","description":"Enables the Realtime Translation feature.","default":false},"reply_mailer_migration":{"type":"boolean","description":"Enables the Reply Mailer Migration feature.","default":false},"report_rollup":{"type":"boolean","description":"Enables the Report Rollup feature.","default":false},"reports":{"type":"boolean","description":"Enables the Reports feature.","default":true},"sales_management":{"type":"boolean","description":"Enables the Sales Management feature.","default":false},"saml":{"type":"boolean","description":"Enables the SAML feature.","default":false},"search_with_gin":{"type":"boolean","description":"Enables the Search messages with GIN feature.","default":false},"session_analytics":{"type":"boolean","description":"Enables the Session Analytics feature.","default":false},"setup_blueprints":{"type":"boolean","description":"Enables the Setup Blueprints feature.","default":false},"shopify_integration":{"type":"boolean","description":"Enables the Shopify Integration feature.","default":false},"sla":{"type":"boolean","description":"Enables the SLA feature.","default":false},"smart_routing":{"type":"boolean","description":"Enables the Smart Routing feature.","default":false},"social_collaboration":{"type":"boolean","description":"Enables the Social Collaboration Network (Matrix) feature.","default":false},"tasks":{"type":"boolean","description":"Enables the Tasks feature.","default":false},"team_management":{"type":"boolean","description":"Enables the Team Management feature.","default":true},"unified_revenue_ledger":{"type":"boolean","description":"Enables the Unified Revenue Ledger feature.","default":false},"usage_metering":{"type":"boolean","description":"Enables the Usage Metering feature.","default":false},"voice_recorder":{"type":"boolean","description":"Enables the Voice Recorder feature.","default":true},"whatsapp_campaign":{"type":"boolean","description":"Enables the WhatsApp Campaign feature.","default":false},"whatsapp_embedded_signup":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup feature. Deprecated flag, kept for backwards compatibility.","default":false},"whatsapp_hub":{"type":"boolean","description":"Enables the WhatsApp Hub feature.","default":false},"whatsapp_hybrid_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Inbox feature.","default":false},"whatsapp_hybrid_unified_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Unified Inbox feature.","default":false},"whatsapp_inbox_suite":{"type":"boolean","description":"Enables the WhatsApp Inbox Suite feature.","default":false},"whatsapp_mobile_egress":{"type":"boolean","description":"Enables the WhatsApp Web Mobile Connection feature.","default":false},"whatsapp_web_proxy":{"type":"boolean","description":"Enables the WhatsApp Web Global Proxy feature.","default":false},"white_label":{"type":"boolean","description":"Enables the White Label feature.","default":false},"workforce_management":{"type":"boolean","description":"Enables the Team Management feature.","default":false}}},"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","additionalProperties":true,"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","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":{},"skip":true},"domain":"example.com","support_email":"agent@example.com","status":"active","features":{"account_brain":false,"ads_conversion_tracking":false,"ads_manager":false,"advanced_assignment":false,"advanced_search":false,"advanced_search_indexing":false,"affiliate_program":false,"agent_bots":true,"agent_management":true,"ai_onboarding":false,"assignment_v2":true,"audit_logs":false,"auto_resolve_conversations":true,"automations":true,"bug_reports":true,"calendar":false,"campaigns":true,"canned_responses":true,"captain_document_auto_sync":false,"captain_integration":false,"captain_integration_v2":false,"captain_tasks":false,"captain_v1_action_classifier":false,"catalog":true,"channel_email":true,"channel_facebook":true,"channel_instagram":true,"channel_tiktok":true,"channel_voice":false,"channel_website":true,"chatwoot_v4":true,"commerce_recovery":false,"companies":false,"contact_chatwoot_support_team":true,"contracts":false,"conversation_glance_signals":false,"conversation_required_attributes":false,"conversation_unread_counts":true,"crm":true,"crm_integration":false,"crm_pipelines":true,"crm_v2":false,"csat_review_notes":false,"custom_attributes":true,"custom_reply_domain":false,"custom_reply_email":false,"custom_roles":false,"custom_tools":false,"dashboard_apps_native_surfaces":false,"disable_branding":false,"email_continuity_on_api_channel":false,"engagement_tracking":false,"field_level_permissions":true,"flow_builder":false,"flow_builder_runtime_v2":false,"follow_ups":false,"governance_lgpd":false,"granular_permissions":true,"growth_ads":false,"growth_social":false,"growth_social_automation":false,"guided_tours":false,"help_center":true,"help_center_embedding_search":false,"inbound_emails":true,"inbox_management":true,"inbox_view":false,"insert_article_in_reply":false,"integrations":true,"internal_chat":false,"ip_lookup":false,"labels":true,"launch_group_distribution":false,"linear_integration":false,"macros":true,"maestro_byok":true,"maestro_global_keys":false,"mcp":false,"media_library":true,"message_reply_to":false,"message_scheduling":false,"native_advanced_search":false,"native_audit_trail":false,"native_event_pipeline_v2":false,"notion_integration":false,"orders_registry":false,"organizations":false,"outbound_agent_name_header":false,"payments":false,"platform_governance":true,"quoted_email_reply":false,"realtime_translation":false,"reply_mailer_migration":false,"report_rollup":false,"reports":true,"sales_management":false,"saml":false,"search_with_gin":false,"session_analytics":false,"setup_blueprints":false,"shopify_integration":false,"sla":false,"smart_routing":false,"social_collaboration":false,"tasks":false,"team_management":true,"unified_revenue_ledger":false,"usage_metering":false,"voice_recorder":true,"whatsapp_campaign":false,"whatsapp_embedded_signup":false,"whatsapp_hub":false,"whatsapp_hybrid_inbox":false,"whatsapp_hybrid_unified_inbox":false,"whatsapp_inbox_suite":false,"whatsapp_mobile_egress":false,"whatsapp_web_proxy":false,"white_label":false,"workforce_management":false},"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_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":"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"}}}}}},"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"}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}},"404":{"description":"The given account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":{"inbound_emails":true,"help_center":true,"campaigns":false,"account_brain":false,"ads_conversion_tracking":false,"ads_manager":false,"advanced_assignment":false,"advanced_search":false,"advanced_search_indexing":false,"affiliate_program":false,"agent_bots":true,"agent_management":true,"ai_onboarding":false,"assignment_v2":true,"audit_logs":false,"auto_resolve_conversations":true,"automations":true,"bug_reports":true,"calendar":false,"canned_responses":true,"captain_document_auto_sync":false,"captain_integration":false,"captain_integration_v2":false,"captain_tasks":false,"captain_v1_action_classifier":false,"catalog":true,"channel_email":true,"channel_facebook":true,"channel_instagram":true,"channel_tiktok":true,"channel_voice":false,"channel_website":true,"chatwoot_v4":true,"commerce_recovery":false,"companies":false,"contact_chatwoot_support_team":true,"contracts":false,"conversation_glance_signals":false,"conversation_required_attributes":false,"conversation_unread_counts":true,"crm":true,"crm_integration":false,"crm_pipelines":true,"crm_v2":false,"csat_review_notes":false,"custom_attributes":true,"custom_reply_domain":false,"custom_reply_email":false,"custom_roles":false,"custom_tools":false,"dashboard_apps_native_surfaces":false,"disable_branding":false,"email_continuity_on_api_channel":false,"engagement_tracking":false,"field_level_permissions":true,"flow_builder":false,"flow_builder_runtime_v2":false,"follow_ups":false,"governance_lgpd":false,"granular_permissions":true,"growth_ads":false,"growth_social":false,"growth_social_automation":false,"guided_tours":false,"help_center_embedding_search":false,"inbox_management":true,"inbox_view":false,"insert_article_in_reply":false,"integrations":true,"internal_chat":false,"ip_lookup":false,"labels":true,"launch_group_distribution":false,"linear_integration":false,"macros":true,"maestro_byok":true,"maestro_global_keys":false,"mcp":false,"media_library":true,"message_reply_to":false,"message_scheduling":false,"native_advanced_search":false,"native_audit_trail":false,"native_event_pipeline_v2":false,"notion_integration":false,"orders_registry":false,"organizations":false,"outbound_agent_name_header":false,"payments":false,"platform_governance":true,"quoted_email_reply":false,"realtime_translation":false,"reply_mailer_migration":false,"report_rollup":false,"reports":true,"sales_management":false,"saml":false,"search_with_gin":false,"session_analytics":false,"setup_blueprints":false,"shopify_integration":false,"sla":false,"smart_routing":false,"social_collaboration":false,"tasks":false,"team_management":true,"unified_revenue_ledger":false,"usage_metering":false,"voice_recorder":true,"whatsapp_campaign":false,"whatsapp_embedded_signup":false,"whatsapp_hub":false,"whatsapp_hybrid_inbox":false,"whatsapp_hybrid_unified_inbox":false,"whatsapp_inbox_suite":false,"whatsapp_mobile_egress":false,"whatsapp_web_proxy":false,"white_label":false,"workforce_management":false},"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_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":"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"}}}}}},"delete":{"tags":["Accounts"],"operationId":"delete-an-account","summary":"Delete an Account","description":"Delete an Account","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"put":{"tags":["Platform Accounts"],"operationId":"auto_put_platform_api_v1_accounts_id","summary":"Update accounts","description":"Updates the account identified by the path parameters with the submitted attributes.","security":[{"platformAppApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"locale":{"type":"string","enum":["en","pt_BR","es"]},"domain":{"type":"string"},"support_email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","suspended"]},"features":{"type":"object","additionalProperties":false,"description":"Free-form object.","properties":{"account_brain":{"type":"boolean","description":"Enables the Account Brain feature.","default":false},"ads_conversion_tracking":{"type":"boolean","description":"Enables the Ad Conversion Tracking (Meta CAPI) feature.","default":false},"ads_manager":{"type":"boolean","description":"Enables the Ads Manager feature.","default":false},"advanced_assignment":{"type":"boolean","description":"Enables the Advanced Assignment feature.","default":false},"advanced_search":{"type":"boolean","description":"Enables the Advanced Search feature.","default":false},"advanced_search_indexing":{"type":"boolean","description":"Enables the Advanced Search Indexing feature.","default":false},"affiliate_program":{"type":"boolean","description":"Enables the Affiliate Program feature.","default":false},"agent_bots":{"type":"boolean","description":"Enables the Agent Bots feature.","default":true},"agent_management":{"type":"boolean","description":"Enables the Agent Management feature.","default":true},"ai_onboarding":{"type":"boolean","description":"Enables the AI Onboarding (Generative Setup) feature.","default":false},"assignment_v2":{"type":"boolean","description":"Enables the Assignment V2 feature.","default":true},"audit_logs":{"type":"boolean","description":"Enables the Audit Logs feature.","default":false},"auto_resolve_conversations":{"type":"boolean","description":"Enables the Auto Resolve Conversations feature.","default":true},"automations":{"type":"boolean","description":"Enables the Automations feature.","default":true},"bug_reports":{"type":"boolean","description":"Enables the Bug Reports feature.","default":true},"calendar":{"type":"boolean","description":"Enables the Calendar feature.","default":false},"campaigns":{"type":"boolean","description":"Enables the Campaigns feature.","default":true},"canned_responses":{"type":"boolean","description":"Enables the Canned Responses feature.","default":true},"captain_document_auto_sync":{"type":"boolean","description":"Enables the Captain Document Auto Sync feature.","default":false},"captain_integration":{"type":"boolean","description":"Enables the Captain feature.","default":false},"captain_integration_v2":{"type":"boolean","description":"Enables the Captain V2 feature.","default":false},"captain_tasks":{"type":"boolean","description":"Enables the Captain Tasks feature.","default":false},"captain_v1_action_classifier":{"type":"boolean","description":"Enables the Captain V1 Action Classifier feature.","default":false},"catalog":{"type":"boolean","description":"Enables the Product Catalog feature.","default":true},"channel_email":{"type":"boolean","description":"Enables the Email Channel feature.","default":true},"channel_facebook":{"type":"boolean","description":"Enables the Facebook Channel feature.","default":true},"channel_instagram":{"type":"boolean","description":"Enables the Instagram Channel feature.","default":true},"channel_tiktok":{"type":"boolean","description":"Enables the TikTok Channel feature.","default":true},"channel_voice":{"type":"boolean","description":"Enables the Voice Channel feature.","default":false},"channel_website":{"type":"boolean","description":"Enables the Website Channel feature.","default":true},"chatwoot_v4":{"type":"boolean","description":"Enables the Chatwoot V4 feature.","default":true},"commerce_recovery":{"type":"boolean","description":"Enables the Commerce Recovery (Sales Recovery) feature.","default":false},"companies":{"type":"boolean","description":"Enables the Companies feature.","default":false},"contact_chatwoot_support_team":{"type":"boolean","description":"Enables the Contact Chatwoot Support Team feature.","default":true},"contracts":{"type":"boolean","description":"Enables the Contracts \u0026 E-signature feature.","default":false},"conversation_glance_signals":{"type":"boolean","description":"Enables the Conversation Glance Signals feature.","default":false},"conversation_required_attributes":{"type":"boolean","description":"Enables the Required Conversation Attributes feature.","default":false},"conversation_unread_counts":{"type":"boolean","description":"Enables the Conversation Unread Counts feature.","default":true},"crm":{"type":"boolean","description":"Enables the CRM feature.","default":true},"crm_integration":{"type":"boolean","description":"Enables the CRM Integration feature.","default":false},"crm_pipelines":{"type":"boolean","description":"Enables the CRM Pipelines feature.","default":true},"crm_v2":{"type":"boolean","description":"Enables the CRM V2 feature.","default":false},"csat_review_notes":{"type":"boolean","description":"Enables the CSAT Review Notes feature.","default":false},"custom_attributes":{"type":"boolean","description":"Enables the Custom Attributes feature.","default":true},"custom_reply_domain":{"type":"boolean","description":"Enables the Custom Reply Domain feature.","default":false},"custom_reply_email":{"type":"boolean","description":"Enables the Custom Reply Email feature.","default":false},"custom_roles":{"type":"boolean","description":"Enables the Custom Roles feature.","default":false},"custom_tools":{"type":"boolean","description":"Enables the Custom Tools feature.","default":false},"dashboard_apps_native_surfaces":{"type":"boolean","description":"Enables the Dashboard Apps Native Surfaces feature.","default":false},"disable_branding":{"type":"boolean","description":"Enables the Disable Branding feature. Deprecated flag, kept for backwards compatibility.","default":false},"email_continuity_on_api_channel":{"type":"boolean","description":"Enables the Email Continuity on API Channel feature.","default":false},"engagement_tracking":{"type":"boolean","description":"Enables the Engagement \u0026 Lead Score feature.","default":false},"field_level_permissions":{"type":"boolean","description":"Enables the Field-level Permissions feature.","default":true},"flow_builder":{"type":"boolean","description":"Enables the Flow Builder feature.","default":false},"flow_builder_runtime_v2":{"type":"boolean","description":"Enables the Flow Builder Runtime V2 feature.","default":false},"follow_ups":{"type":"boolean","description":"Enables the Follow-up feature.","default":false},"governance_lgpd":{"type":"boolean","description":"Enables the Governance \u0026 LGPD feature.","default":false},"granular_permissions":{"type":"boolean","description":"Enables the Granular Permissions feature.","default":true},"growth_ads":{"type":"boolean","description":"Enables the Growth Ads (CTWA \u0026 Lead Ads) feature.","default":false},"growth_social":{"type":"boolean","description":"Enables the Growth Social (Comment-to-DM) feature.","default":false},"growth_social_automation":{"type":"boolean","description":"Enables the Growth Social Automation (IG/TikTok/YouTube) feature.","default":false},"guided_tours":{"type":"boolean","description":"Enables the Guided Tours feature.","default":false},"help_center":{"type":"boolean","description":"Enables the Help Center feature.","default":true},"help_center_embedding_search":{"type":"boolean","description":"Enables the Help Center Embedding Search feature.","default":false},"inbound_emails":{"type":"boolean","description":"Enables the Inbound Emails feature.","default":true},"inbox_management":{"type":"boolean","description":"Enables the Inbox Management feature.","default":true},"inbox_view":{"type":"boolean","description":"Enables the Inbox View feature.","default":false},"insert_article_in_reply":{"type":"boolean","description":"Enables the Insert Article in Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"integrations":{"type":"boolean","description":"Enables the Integrations feature.","default":true},"internal_chat":{"type":"boolean","description":"Enables the Internal Chat feature.","default":false},"ip_lookup":{"type":"boolean","description":"Enables the IP Lookup feature.","default":false},"labels":{"type":"boolean","description":"Enables the Labels feature.","default":true},"launch_group_distribution":{"type":"boolean","description":"Enables the Launch Group Distribution feature.","default":false},"linear_integration":{"type":"boolean","description":"Enables the Linear Integration feature.","default":false},"macros":{"type":"boolean","description":"Enables the Macros feature.","default":true},"maestro_byok":{"type":"boolean","description":"Enables the Maestro BYOK (Account LLM Keys) feature.","default":true},"maestro_global_keys":{"type":"boolean","description":"Enables the Maestro Installation LLM Keys (Global Fallback) feature.","default":false},"mcp":{"type":"boolean","description":"Enables the MCP (Model Context Protocol) feature.","default":false},"media_library":{"type":"boolean","description":"Enables the Media Library feature.","default":true},"message_reply_to":{"type":"boolean","description":"Enables the Message Reply To feature. Deprecated flag, kept for backwards compatibility.","default":false},"message_scheduling":{"type":"boolean","description":"Enables the Message Scheduling feature.","default":false},"native_advanced_search":{"type":"boolean","description":"Enables the Advanced Search (Native) feature.","default":false},"native_audit_trail":{"type":"boolean","description":"Enables the Audit Trail (Native) feature.","default":false},"native_event_pipeline_v2":{"type":"boolean","description":"Enables the Native Event Pipeline V2 feature.","default":false},"notion_integration":{"type":"boolean","description":"Enables the Notion Integration feature.","default":false},"orders_registry":{"type":"boolean","description":"Enables the CRM Orders Registry feature.","default":false},"organizations":{"type":"boolean","description":"Enables the Organizations (Companies \u0026 Relationships) feature.","default":false},"outbound_agent_name_header":{"type":"boolean","description":"Enables the Outbound Agent Name Header feature.","default":false},"payments":{"type":"boolean","description":"Enables the Payments feature.","default":false},"platform_governance":{"type":"boolean","description":"Enables the Platform Governance feature.","default":true},"quoted_email_reply":{"type":"boolean","description":"Enables the Quoted Email Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"realtime_translation":{"type":"boolean","description":"Enables the Realtime Translation feature.","default":false},"reply_mailer_migration":{"type":"boolean","description":"Enables the Reply Mailer Migration feature.","default":false},"report_rollup":{"type":"boolean","description":"Enables the Report Rollup feature.","default":false},"reports":{"type":"boolean","description":"Enables the Reports feature.","default":true},"sales_management":{"type":"boolean","description":"Enables the Sales Management feature.","default":false},"saml":{"type":"boolean","description":"Enables the SAML feature.","default":false},"search_with_gin":{"type":"boolean","description":"Enables the Search messages with GIN feature.","default":false},"session_analytics":{"type":"boolean","description":"Enables the Session Analytics feature.","default":false},"setup_blueprints":{"type":"boolean","description":"Enables the Setup Blueprints feature.","default":false},"shopify_integration":{"type":"boolean","description":"Enables the Shopify Integration feature.","default":false},"sla":{"type":"boolean","description":"Enables the SLA feature.","default":false},"smart_routing":{"type":"boolean","description":"Enables the Smart Routing feature.","default":false},"social_collaboration":{"type":"boolean","description":"Enables the Social Collaboration Network (Matrix) feature.","default":false},"tasks":{"type":"boolean","description":"Enables the Tasks feature.","default":false},"team_management":{"type":"boolean","description":"Enables the Team Management feature.","default":true},"unified_revenue_ledger":{"type":"boolean","description":"Enables the Unified Revenue Ledger feature.","default":false},"usage_metering":{"type":"boolean","description":"Enables the Usage Metering feature.","default":false},"voice_recorder":{"type":"boolean","description":"Enables the Voice Recorder feature.","default":true},"whatsapp_campaign":{"type":"boolean","description":"Enables the WhatsApp Campaign feature.","default":false},"whatsapp_embedded_signup":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup feature. Deprecated flag, kept for backwards compatibility.","default":false},"whatsapp_hub":{"type":"boolean","description":"Enables the WhatsApp Hub feature.","default":false},"whatsapp_hybrid_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Inbox feature.","default":false},"whatsapp_hybrid_unified_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Unified Inbox feature.","default":false},"whatsapp_inbox_suite":{"type":"boolean","description":"Enables the WhatsApp Inbox Suite feature.","default":false},"whatsapp_mobile_egress":{"type":"boolean","description":"Enables the WhatsApp Web Mobile Connection feature.","default":false},"whatsapp_web_proxy":{"type":"boolean","description":"Enables the WhatsApp Web Global Proxy feature.","default":false},"white_label":{"type":"boolean","description":"Enables the White Label feature.","default":false},"workforce_management":{"type":"boolean","description":"Enables the Team Management feature.","default":false}}},"limits":{"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":{"name":"Sample Name","locale":"en","domain":"example.com","support_email":"agent@example.com","status":"active","features":{"account_brain":false,"ads_conversion_tracking":false,"ads_manager":false,"advanced_assignment":false,"advanced_search":false,"advanced_search_indexing":false,"affiliate_program":false,"agent_bots":true,"agent_management":true,"ai_onboarding":false,"assignment_v2":true,"audit_logs":false,"auto_resolve_conversations":true,"automations":true,"bug_reports":true,"calendar":false,"campaigns":true,"canned_responses":true,"captain_document_auto_sync":false,"captain_integration":false,"captain_integration_v2":false,"captain_tasks":false,"captain_v1_action_classifier":false,"catalog":true,"channel_email":true,"channel_facebook":true,"channel_instagram":true,"channel_tiktok":true,"channel_voice":false,"channel_website":true,"chatwoot_v4":true,"commerce_recovery":false,"companies":false,"contact_chatwoot_support_team":true,"contracts":false,"conversation_glance_signals":false,"conversation_required_attributes":false,"conversation_unread_counts":true,"crm":true,"crm_integration":false,"crm_pipelines":true,"crm_v2":false,"csat_review_notes":false,"custom_attributes":true,"custom_reply_domain":false,"custom_reply_email":false,"custom_roles":false,"custom_tools":false,"dashboard_apps_native_surfaces":false,"disable_branding":false,"email_continuity_on_api_channel":false,"engagement_tracking":false,"field_level_permissions":true,"flow_builder":false,"flow_builder_runtime_v2":false,"follow_ups":false,"governance_lgpd":false,"granular_permissions":true,"growth_ads":false,"growth_social":false,"growth_social_automation":false,"guided_tours":false,"help_center":true,"help_center_embedding_search":false,"inbound_emails":true,"inbox_management":true,"inbox_view":false,"insert_article_in_reply":false,"integrations":true,"internal_chat":false,"ip_lookup":false,"labels":true,"launch_group_distribution":false,"linear_integration":false,"macros":true,"maestro_byok":true,"maestro_global_keys":false,"mcp":false,"media_library":true,"message_reply_to":false,"message_scheduling":false,"native_advanced_search":false,"native_audit_trail":false,"native_event_pipeline_v2":false,"notion_integration":false,"orders_registry":false,"organizations":false,"outbound_agent_name_header":false,"payments":false,"platform_governance":true,"quoted_email_reply":false,"realtime_translation":false,"reply_mailer_migration":false,"report_rollup":false,"reports":true,"sales_management":false,"saml":false,"search_with_gin":false,"session_analytics":false,"setup_blueprints":false,"shopify_integration":false,"sla":false,"smart_routing":false,"social_collaboration":false,"tasks":false,"team_management":true,"unified_revenue_ledger":false,"usage_metering":false,"voice_recorder":true,"whatsapp_campaign":false,"whatsapp_embedded_signup":false,"whatsapp_hub":false,"whatsapp_hybrid_inbox":false,"whatsapp_hybrid_unified_inbox":false,"whatsapp_inbox_suite":false,"whatsapp_mobile_egress":false,"whatsapp_web_proxy":false,"white_label":false,"workforce_management":false},"limits":{},"custom_attributes":{}}}}}}},"/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"}}}}}},"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"}}}}}},"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"}}}},"404":{"description":"The account does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"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}}}},"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"}}}}}}},"/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}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The given agent bot ID does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"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}}}},"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"}}}}}},"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"}}}},"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}}}},"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"}}}}}},"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"}}}},"404":{"description":"The agent bot does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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}}}},"401":{"description":"Missing/invalid PlatformApp credential, bot permission, or account permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The agent bot does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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"}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given user does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given user does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given user does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given inbox does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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"}}}},"404":{"description":"The given contact does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"patch":{"tags":["Contacts API"],"operationId":"update-a-contact","summary":"Update a contact","description":"Update a contact's attributes","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"}}}}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"},"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","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"}}}}}},"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":{"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"},"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","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"}}}}}}},"/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":{"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"},"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","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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{"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"},"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","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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","description":"Updates the last seen time of the contact in a conversation","security":[],"responses":{"200":{"description":"Last seen updated successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{"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"},"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","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"}}}}}},"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":{"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"},"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","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"}}}}}}},"/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":{"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"},"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","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"}}}}}},"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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}}}},"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"}}},"404":{"description":"Resource not found"}}}},"/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"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"put":{"tags":["Account"],"operationId":"auto_put_api_v1_accounts_id","summary":"Update accounts","description":"Updates the account identified by the path parameters with the submitted attributes.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"string"},"created_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"},"custom_attributes":{"type":"object","properties":{"plan_name":{"type":"string"},"subscribed_quantity":{"type":"string"},"subscription_status":{"type":"string"},"subscription_ends_on":{"type":"string"},"website":{"type":"string"},"industry":{"type":"string"},"company_size":{"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"},"logo":{"type":"string"},"referral_source":{"type":"string"},"brand_info":{"type":"string"},"guided_tours":{"type":"object","properties":{"autoplay":{"type":"string"},"reset_at":{"type":"string","format":"date-time"}}}}},"onboarding_step":{"type":"string"},"help_center_generation_id":{"type":"integer"},"marked_for_deletion_at":{"type":"string","format":"date-time"},"marked_for_deletion_reason":{"type":"string"},"domain":{"type":"string"},"features":{"type":"string"},"session_analytics":{"type":"string"},"governance":{"type":"string"},"id":{"type":"integer"},"locale":{"type":"string"},"name":{"type":"string"},"support_email":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","suspended"]},"cache_keys":{"type":"object","additionalProperties":true,"description":"Per-collection cache-key fingerprints used for client cache invalidation."}}},"example":{"settings":"sample settings","created_at":"2026-01-15T10:30:00.000Z","timezone":"America/Sao_Paulo","custom_attributes":{"plan_name":"sample plan name","subscribed_quantity":"sample subscribed quantity","subscription_status":"sample subscription status","subscription_ends_on":"sample subscription ends on","website":"sample website","industry":"sample industry","company_size":"sample company size","timezone":"America/Sao_Paulo","logo":"sample logo","referral_source":"sample referral source","brand_info":"sample brand info","guided_tours":{"autoplay":"sample autoplay","reset_at":"2026-01-15T10:30:00.000Z"}},"onboarding_step":"sample onboarding step","help_center_generation_id":1,"marked_for_deletion_at":"2026-01-15T10:30:00.000Z","marked_for_deletion_reason":"sample marked for deletion reason","domain":"example.com","features":"sample features","session_analytics":"sample session analytics","governance":"sample governance","id":1,"locale":"en","name":"Sample Name","support_email":"agent@example.com","status":"active","cache_keys":{}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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/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}}],"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"}}}},"422":{"description":"Feature not enabled or not available in current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{},"account_id":1,"access_token":"sample-token","system_bot":true}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":{}}}}},"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":{},"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{},"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The given agent bot ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":{}}}}},"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":{},"account_id":1,"access_token":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The agent bot does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"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","account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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","thumbnail":"sample thumbnail","custom_role_id":1}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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","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"}}}}}},"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","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","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"}}}}}}},"/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","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","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"}}}},"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"}}}}}},"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","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","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"}}}},"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"}}}}}},"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"}}}},"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"}}}}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"The given attribute ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}],"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"}}}}}},"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,"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"}}}}}}},"/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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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,"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]},"hmac_verified":true}}]}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}],"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"}}}}}}},"/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"}}}}}}},"/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"}}}},"422":{"description":"Incorrect payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Incorrect payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"One or both contacts not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}],"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"}}}}}},"post":{"tags":["Automation Rule"],"operationId":"add-new-automation-rule-to-account","summary":"Add a new automation rule","description":"Add a new automation rule to account","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,"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"}],"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"}}}}}}},"/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","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"}}}},"404":{"description":"The given rule ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"patch":{"tags":["Automation Rule"],"operationId":"update-automation-rule-in-account","summary":"Update automation rule in Account","description":"Update a automation rule in account","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,"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"}],"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"}}}},"404":{"description":"Rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"automation rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"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,"files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"event_name":{"type":"string"},"active":{"type":"boolean"},"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":{"name":"Sample Name","description":"A short description.","event_name":"sample event name","active":true,"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":{"color":"#FFFFFF","custom_domain":"help.example.com","header_text":"Handbook","homepage_link":"https://www.example.com/","name":"Handbook","page_title":"Handbook","slug":"handbook","archived":false,"config":{"allowed_locales":["en","es"],"default_locale":"en"}}}}},"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":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"},"logo":{"id":1,"portal_id":1,"file_type":"image","account_id":1,"file_url":"https://example.com/resource","blob_id":1,"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"}}}}}},"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","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","business_name":"sample business name","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","medium":"sample medium","provider":"default"},"logo":{"id":19399916,"portal_id":4,"file_type":"image/png","account_id":1,"file_url":"https://example.com/logo.png","blob_id":21239614,"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"}}}}}}},"/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_create_update_payload"},"example":{"color":"#FFFFFF","custom_domain":"help.example.com","header_text":"Handbook","homepage_link":"https://www.example.com/","name":"Handbook","page_title":"Handbook","slug":"handbook","archived":false,"config":{"allowed_locales":["en","es"],"default_locale":"en"}}}}},"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,"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","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","medium":"sample medium","provider":"default"},"logo":{"id":123,"portal_id":123,"file_type":"image/png","account_id":123,"file_url":"https://example.com/logo.png","blob_id":123,"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"}}}},"404":{"description":"Portal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":"string"}}}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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":"sample draft"}],"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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"},"403":{"description":"Forbidden"},"404":{"description":"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":"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":"string"}}}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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":"sample draft"}],"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"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"}}}},"required":["portal"]},"example":{"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}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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,"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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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 conversation status."},{"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"}}}}},"example":{"meta":{"mine_count":5,"unassigned_count":5,"assigned_count":5,"all_count":5}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_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 conversation status."},{"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},"payload":[{"id":1,"messages":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]},"hmac_verified":true}}]}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_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"}}}}}}},"/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},"payload":[{"id":1,"messages":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]},"hmac_verified":true}}]}}}}},"400":{"description":"Bad Request Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]},"hmac_verified":true}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"patch":{"tags":["Conversations"],"operationId":"update-conversation","summary":"Update Conversation","description":"Update Conversation Attributes","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":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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,"timestamp":12.5,"first_reply_created_at":12.5,"unread_count":5,"last_non_activity_message":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"put":{"tags":["Conversations"],"operationId":"auto_put_api_v1_accounts_account_id_conversations_id","summary":"Update conversations","description":"Updates the conversation 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"string","enum":["low","medium","high","urgent"]}}},"example":{"priority":"low"}}}}},"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":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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, merge these keys into the existing set instead of replacing it. Absent or false replaces the whole set (the dashboard's delete-by-omission behavior).","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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":"Assign 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.","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","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/user"},{"$ref":"#/components/schemas/agent_bot_slim"}]},"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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/api/v1/accounts/{account_id}/inboxes":{"get":{"tags":["Inboxes"],"operationId":"listAllInboxes","summary":"List all inboxes","description":"List all inboxes available in the current account","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":[{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":{"api_key":"your-api-key","api_secret":"your-api-secret","application_id":"your-application-id","account_id":"your-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"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox"},"example":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","business_name":"My Business"}},"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","business_name":"My Business"}},"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","business_name":"My Business"}},"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","business_name":"My Business"}},"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","business_name":"My Business"}},"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"}},"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 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":{"api_key":"your-api-key","api_secret":"your-api-secret","application_id":"your-application-id","account_id":"your-account-id","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id"},"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","business_name":"My Business"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inbox"},"example":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":{"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"example":{"channel":[{}]}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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}/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":{},"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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}}},"example":{"agent_bot":1}}}},"responses":{"204":{"description":"Success"},"404":{"description":"Inbox not found, Agent bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"The given label ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}}}},"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"}}}},"404":{"description":"The label does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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,"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","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":[{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"sender":{}}]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"post":{"tags":["Messages"],"operationId":"create-a-new-message-in-a-conversation","summary":"Create New Message","description":"Create a new message in the conversation.\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\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":{"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","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":{"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":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/generic_id"},{"$ref":"#/components/schemas/message"}]},"example":{"id":1,"content":"Sample content text.","account_id":1,"inbox_id":1,"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":{"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"},"sender_type":"Contact","sender_id":1,"external_source_ids":{},"additional_attributes":{},"processed_message_content":"sample processed message content","sentiment":{},"conversation":{},"attachment":{},"sender":{}}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}],"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"}}}},"404":{"description":"The message or conversation does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"patch":{"tags":["Conversations"],"operationId":"auto_patch_api_v1_accounts_account_id_conversations_conversation_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":{"id":{"type":"integer"},"content":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"echo_id":{"type":"integer"},"conversation_id":{"type":"integer"},"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)."},"status":{"type":"string","enum":["sent","delivered","read","failed"]},"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"},"private":{"type":"string"},"source_id":{"type":"integer"},"sender":{"type":"string"},"attachments":{"type":"array","items":{"type":"string"}},"set":{"type":"string"}}},"example":{"id":1,"content":"Sample content text.","inbox_id":1,"logical_inbox_id":1,"echo_id":1,"conversation_id":1,"message_type":"incoming","content_type":"text","status":"sent","content_attributes":{},"created_at":1,"private":"sample private","source_id":1,"sender":"sample sender","attachments":["sample attachment"],"set":"sample set"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"target_language":{"type":"string"},"status":{"type":"string","enum":["sent","delivered","read","failed"]},"external_error":{"type":"string"},"emoji":{"type":"string"},"by":{"type":"string"},"content":{"type":"string"},"response":{"type":"string"},"extra_guest_count":{"type":"integer"},"options":{"type":"array","items":{"type":"string"}}}},"example":{"id":1,"target_language":"sample target language","status":"sent","external_error":"sample external error","emoji":"sample emoji","by":"sample by","content":"Sample content text.","response":"sample response","extra_guest_count":5,"options":["sample option"]}}}}},"put":{"tags":["Conversations"],"operationId":"auto_put_api_v1_accounts_account_id_conversations_conversation_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":{"id":{"type":"integer"},"content":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"echo_id":{"type":"integer"},"conversation_id":{"type":"integer"},"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)."},"status":{"type":"string","enum":["sent","delivered","read","failed"]},"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"},"private":{"type":"string"},"source_id":{"type":"integer"},"sender":{"type":"string"},"attachments":{"type":"array","items":{"type":"string"}},"set":{"type":"string"}}},"example":{"id":1,"content":"Sample content text.","inbox_id":1,"logical_inbox_id":1,"echo_id":1,"conversation_id":1,"message_type":"incoming","content_type":"text","status":"sent","content_attributes":{},"created_at":1,"private":"sample private","source_id":1,"sender":"sample sender","attachments":["sample attachment"],"set":"sample set"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"target_language":{"type":"string"},"status":{"type":"string","enum":["sent","delivered","read","failed"]},"external_error":{"type":"string"},"emoji":{"type":"string"},"by":{"type":"string"},"content":{"type":"string"},"response":{"type":"string"},"extra_guest_count":{"type":"integer"},"options":{"type":"array","items":{"type":"string"}}}},"example":{"id":1,"target_language":"sample target language","status":"sent","external_error":"sample external error","emoji":"sample emoji","by":"sample by","content":"Sample content text.","response":"sample response","extra_guest_count":5,"options":["sample option"]}}}}}},"/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"}}}},"404":{"description":"Url not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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"}}}}}},"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"}}}},"404":{"description":"The hook does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":[]}],"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"put":{"tags":["Profile"],"operationId":"updateProfile","summary":"Update user profile","description":"Update the user profile details","security":[{"userApiKey":[]}],"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","permissions":["sample permission"],"availability":"online","availability_status":"online","auto_offline":true,"custom_role_id":1,"custom_role":{}}]}}}},"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":{"type":"object","properties":{"access_token":{"type":"string"},"account_id":{"type":["integer","null"]},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"email":{"type":"string","format":"email"},"hmac_identifier":{"type":"string"},"id":{"type":"integer"},"inviter_id":{"type":["integer","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"pubsub_token":{"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, ...)."},"role":{"type":["string","null"],"enum":["agent","administrator",null]},"ui_settings":{"type":"string"},"uid":{"type":"string"},"type":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"onboarding_step":{"type":"string"},"active_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["agent","administrator"]},"permissions":{"type":"string"},"access_role_id":{"type":["integer","null"]},"access_role":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"type":"string"}}}}}}}},"example":{"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","id":1,"inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","custom_attributes":{},"role":"agent","ui_settings":"sample ui settings","uid":"sample uid","type":"sample type","accounts":[{"id":1,"name":"Sample Name","status":"active","onboarding_step":"sample onboarding step","active_at":"2026-01-15T10:30:00.000Z","role":"agent","permissions":"sample permissions","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":"sample field permissions"}}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"required":["profile"]},"example":{"profile":{"current_password":"sample current password","password":"sample-password","password_confirmation":"sample password confirmation"}}}}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"The given team ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}}}},"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"}}}}}},"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"}}}},"404":{"description":"The team does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"Team not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"User must exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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 all custom filters in a category of a user","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"}}}}}},"post":{"tags":["Custom Filters"],"operationId":"create-a-custom-filter","summary":"Create a custom filter","description":"Create a custom filter in the account","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"}}}}}}},"/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":"Get the details of a custom filter in the account","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"}}}},"404":{"description":"The given team ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"patch":{"tags":["Custom Filters"],"operationId":"update-a-custom-filter","summary":"Update a custom filter","security":[{"userApiKey":[]}],"description":"Update a custom filter's attributes","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"}}}}}},"delete":{"tags":["Custom Filters"],"operationId":"delete-a-custom-filter","summary":"Delete a custom filter","security":[{"userApiKey":[]}],"description":"Delete a custom filter from the account","responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The custom filter does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"put":{"tags":["Custom Filters"],"operationId":"auto_put_api_v1_accounts_account_id_custom_filters_id","summary":"Update custom filters","description":"Updates the custom filter 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"},"filter_type":{"type":"string","enum":["conversation","contact","report","crm_item","crm_report","catalog_product","catalog_report","task","organization"]},"query":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"name":"Sample Name","filter_type":"conversation","query":"sample query","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_filter":{"type":"object","properties":{"name":{"type":"string"},"filter_type":{"type":"string","enum":["conversation","contact","report","crm_item","crm_report","catalog_product","catalog_report","task","organization"]},"query":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["custom_filter"]},"example":{"custom_filter":{"name":"Sample Name","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"}}}}}},"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"}}}}}}},"/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"}}}}}},"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":{"type":"object"}}}},"404":{"description":"The webhook does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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"}}}}}}},"/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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}}},"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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given pipeline ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"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"}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"An active pipeline with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The given stage ID does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"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"}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The stage does not exist in the pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}}}},"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},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"404":{"description":"The given item ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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},"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"}}}},"404":{"description":"The given item ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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. Cleared when the deal is reopened."},"close_reason":{"type":"string","description":"Why the deal was won or lost."},"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},"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"}}}},"404":{"description":"The item or target stage does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"404":{"description":"The item or target pipeline does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"422":{"description":"Invalid status value (no write performed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"The item must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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"}}}},"404":{"description":"The item or macro does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"422":{"description":"No fields provided or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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},"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"}}}},"422":{"description":"Invalid status value or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The macro does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}}}},"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","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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"The note or CRM item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","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"}}}},"404":{"description":"The note does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The note does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The attachment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","thumbnail":"sample thumbnail","custom_role_id":1}]}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user_ids":{"type":"string"}}},"example":{"user_ids":"sample user ids"}}}}}},"/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","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"}}}}}},"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","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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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"}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"The checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The item or the line item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"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"}}}}}},"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"}}}},"404":{"description":"The item or the line item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The item does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"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"}}}},"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"}}}}}}},"/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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The organization does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}},"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"}}}},"422":{"description":"Invalid attributes (e.g. fiscal identifier fails validation, hierarchy cycle)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"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"}}}}}}}}},"/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"}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Invalid attributes (e.g. fiscal identifier fails validation, hierarchy cycle)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The organization does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The given organization ID does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The organization or the contact does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The contact is already a member of the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The membership does not exist in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The subject does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"A subject or the relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Invalid edge (e.g. duplicate or self-referencing relationship)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The relationship does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The relationship does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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"}}}},"422":{"description":"Invalid attributes (e.g. duplicate name in the account)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Unknown preset","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"The rejection reason"}}}}}}}}},"/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"}}}},"404":{"description":"The relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The relationship type does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"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"}}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}}},"/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"}}}}},"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"}}}}},"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"}}}}},"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"}}}}}}},"/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}}}},"401":{"description":"Unauthorized"}}}},"/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"}}},"401":{"description":"Unauthorized"}}}},"/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"}}}}},"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"}}}}},"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"},"401":{"description":"Unauthorized"}},"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":"string"},"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":"sample merge","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"422":{"description":"The product must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The product does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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. Answers `200 OK` with an EMPTY body — the created message arrives through the conversation itself, so read it there rather than parsing this response.","security":[{"userApiKey":[]}],"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 dispatched. Empty body — the message surfaces in the conversation."},"404":{"description":"The conversation, a selected kept product, or a selected kept variation does not belong to this account/selection."}}}},"/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"}}}}},"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"}}}},"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":"string"},"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":"sample merge","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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample merge","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}},"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"}}}}},"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"}}}}},"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"}}}}},"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"},"401":{"description":"Unauthorized"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}}},"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":"secret-value"},"username":{"type":"string","description":"Username when type is basic.","example":"sync-user"},"password":{"type":"string","description":"Password when type is basic.","example":"secret-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":"secret-value","header":"X-Api-Key","username":"sync-user","password":"secret-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":"••••••"}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}}}},"delete":{"tags":["Catalog Sync Sources"],"operationId":"delete-catalog-sync-source","summary":"Delete a sync source (admin)","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Success"},"401":{"description":"Unauthorized"}},"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,"created":1,"updated":1,"skipped":1,"failed":1,"meta_validated":1,"dry_run":true},"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"}}}}}}},"/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"}}}},"502":{"description":"Meta could not be queried. No remote write was attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"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"}}}}}}},"/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,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","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"}}}},"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"}}}},"403":{"description":"Administrator access required"},"422":{"description":"Empty, malformed, duplicate, or oversized explicit selection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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,"created":1,"updated":1,"skipped":1,"failed":1,"repaired":1,"meta_validated":1,"dry_run":true,"truncated":true,"failed_ids":[{"external_id":"sample external id","reason":"Sample reason."}],"skipped_ids":[{"external_id":"sample external id","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"}}}}},"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","reason":"Sample reason."}],"created":1,"updated":1,"meta_validated":1,"dry_run":true,"truncated":true,"skipped_ids":[{"external_id":"sample external id","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"}}}},"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"}}}}}}},"/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":[],"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":[],"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":[],"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":[],"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":[],"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"},{"name":"public_id","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the MCP access profile this connection belongs to."}],"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) and must send `Accept: application/json` and `Content-Type: application/json`. 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":{"type":"object","additionalProperties":true,"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},"error":null}}}},"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, 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"}}}},"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"},{"name":"public_id","in":"path","required":true,"description":"Public, non-secret id of the enabled MCP access profile.","schema":{"type":"string"},"example":"a1b2c3d4e5f6g7h8i9j0"}],"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. 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 `Accept: application/json` and `Content-Type: application/json`. 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":{"type":"object","additionalProperties":true,"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":[]},"error":{"code":-32601,"message":"Method not found"}}}}},"202":{"description":"Notification accepted. A JSON-RPC notification has no response body."},"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 or native OAuth server is disabled, or the OAuth resource is unavailable. Dark-shipped surfaces intentionally do not disclose profile existence.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","description":"Availability message.","example":"MCP OAuth connection is unavailable"}}},"example":{"error":"MCP OAuth connection is unavailable"}}}}}},"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/oauth":{"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 whose MFA is no longer enabled. 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. 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 MFA step. `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 Accept: application/json and Content-Type: application/json; batched arrays are rejected. 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":{"type":"object","additionalProperties":true,"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":[]},"error":{"code":-32601,"message":"Method not found"}}}}},"202":{"description":"Notification accepted. A JSON-RPC notification has no response body."},"401":{"description":"Missing, expired, revoked, cross-resource or cross-plane OAuth bearer; or an inactive Super Admin subject whose MFA is no longer enabled. 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 general MCP server or the independently gated Super Admin MCP server is unavailable. The endpoint does not disclose which gate is disabled.","content":{"application/json":{"schema":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","description":"Availability message.","example":"Super Admin MCP OAuth connection is unavailable"}}},"example":{"error":"Super Admin MCP OAuth connection is unavailable"}}}}}},"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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"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":"2025-11-25","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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/platform/api/v1/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","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","authorization_servers","scopes_supported","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"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_chatwoot_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"}}}}},"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":"2025-11-25","authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"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","authorization_servers","scopes_supported","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"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_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp/oauth","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"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":"2025-11-25","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","authorization_servers","scopes_supported","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"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_chatwoot_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"}}}}},"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":"2025-11-25","authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","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","authorization_servers","scopes_supported","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"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_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/super_admin/mcp/oauth","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","authorization_servers":["https://app.example.com/oauth/mcp"],"scopes_supported":["mcp:read","mcp:write","offline_access"],"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","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":["2025-11-25"],"description":"MCP protocol revision implemented by this resource.","example":"2025-11-25"},"x_chatwoot_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"}}}}},"example":{"resource":"https://app.example.com/platform/api/v1/mcp","bearer_methods_supported":["header"],"resource_documentation":"https://app.example.com/","mcp_protocol_version":"2025-11-25","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.","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"}],"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 or deny 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. 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"],"description":"Explicit consent decision from the authenticated human.","example":"approve"}}},"example":{"flow_id":"6e5991d5df9845b8a9d95f7cbec5c8a4","decision":"approve"}}}},"responses":{"302":{"description":"Redirect to the exact registered callback with an authorization code or OAuth denial 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 MFA-verified Super Admin session. 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, MFA is required and must be freshly verified 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":"never-send-a-real-password"},"otp_code":{"type":"string","description":"Optional MFA one-time password. Required for a Super Admin resource 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":"never-send-a-real-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 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":"opaque-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":"opaque-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":"opaque-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":"opaque-refresh-token"},"scope":{"type":"string","description":"Space-delimited scopes actually granted for the exact resource.","example":"mcp:read"}}},"example":{"access_token":"opaque-access-token","token_type":"Bearer","expires_in":900,"scope":"mcp:read","refresh_token":"opaque-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":"opaque-refresh-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":"opaque-refresh-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"}}}}}},"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"}}}}},"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"}}}}},"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"}}}}},"401":{"description":"Unauthorized"}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}},"401":{"description":"Unauthorized"}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or reminder does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or link does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The linkable record is invalid or not in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or dependency does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task or target task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The dependency would create a cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or comment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task or comment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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","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"}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task or checklist item does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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","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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task or attachment does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The file exceeds the upload size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"No fields provided or bulk limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The task does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The task must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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}]}}}},"401":{"description":"Unauthorized"}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"The list must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The list does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}}}}}},"401":{"description":"Unauthorized"}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The template does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"The SLA policy does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity (e.g. no threshold provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"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":"string"},"max_installments":{"type":"string"},"settlement_currency":{"type":"string"},"webhook_reachable":{"type":"boolean"},"webhook_url":{"type":"string"},"webhook_registration_error":{"type":"string"},"last_reconciliation":{"type":"string"},"has_api_key":{"type":"boolean"},"has_secret_key":{"type":"boolean"},"has_webhook_token":{"type":"boolean"},"webhook_email":{"type":"string","format":"email"},"notify_contact_on_paid":{"type":"boolean"},"require_discount_reason":{"type":"boolean"},"installment_interest_mode":{"type":"string","enum":["absorb","passthrough"],"description":"Who pays the interest when a charge is split into installments. `absorb` — the business does (the customer pays the charge amount, split, and the gateway fee comes out of the merchant's net). `passthrough` — the customer does (each installment is grossed up so the merchant receives the full amount). Traces to Payments::InstallmentPricing::MODES; only gateways whose `installment_mode` capability is true can bill the payer for it."},"installment_interest_rate":{"type":["number","null"]},"settings":{"type":"object","additionalProperties":true,"description":"Sanitized, server-managed connection metadata. Provider endpoints are fixed by gateway and environment and cannot be overridden here. The ingestion keys below are written only through the governed ingestion-settings action.","properties":{"orphan_adoption_policy":{"type":"string","enum":["disabled","from_watermark","all"],"default":"disabled","example":"disabled","description":"Adoption of a gateway charge arriving by webhook with no local row. `disabled` never adopts; `from_watermark` adopts only records dated on/after `import_from`; `all` adopts everything. Unrecognized values fall back to `disabled`. Adopted charges are recorded as history and produce no customer-facing or third-party side effect."},"import_from":{"type":"string","format":"date-time","example":"2026-07-01T00:00:00Z","description":"Ingestion watermark; nothing dated before it enters, by import or webhook. Absent means no floor. An unparseable value refuses everything (fail-closed)."}}},"archived_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,"name":"Sample Name","gateway":"asaas","environment":"sandbox","status":"pending","is_default":true,"capabilities":"sample capabilities","max_installments":"sample max installments","settlement_currency":"sample settlement currency","webhook_reachable":true,"webhook_url":"https://example.com/resource","webhook_registration_error":"sample webhook registration error","last_reconciliation":"sample last reconciliation","has_api_key":true,"has_secret_key":true,"has_webhook_token":true,"webhook_email":"agent@example.com","notify_contact_on_paid":true,"require_discount_reason":true,"installment_interest_mode":"absorb","installment_interest_rate":12.5,"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}},"422":{"description":"Unprocessable Entity (gateway rejected the webhook registration)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"The connection must be archived first, or it still has charges/subscriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"The connection does not exist in the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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. 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 or connection name.","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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}],"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"}}}}}},"post":{"tags":["Payment Charges"],"operationId":"create-payment-charge","summary":"Create a charge (avulsa / catalog / 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"},"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/deal."},"currency":{"type":"string","example":"BRL"},"due_date":{"type":"string","format":"date"},"installments":{"type":"integer","minimum":1,"description":"Credit-card installments. Mercado Pago accepts 1..36; the selected connection is capability-gated and provider-specific limits are enforced before persistence."},"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":{"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":{"value":{"type":"number","exclusiveMinimum":0,"maximum":100,"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","deal"],"default":"manual"},"catalog_variant_ids":{"type":"array","items":{"type":"number"},"description":"When source=catalog."},"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,"conversation_id":1,"billing_type":"pix","amount":149.9,"currency":"BRL","due_date":"2026-01-15","installments":1,"gateway_options":{"fine":{"value":2},"interest":{"value":1},"discount":{"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],"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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}}}},"/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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}},"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."}}}}},"example":{"charge":{"amount":149.9,"due_date":"2026-01-15","description":"A short description.","billing_type":"pix"}}}}},"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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"422":{"description":"Unprocessable Entity (settled charge, or the gateway rejected the edit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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."}}}}}}}},"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":{}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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"}}}}}}},"/api/v1/accounts/{account_id}/payments/charges/{id}/refund":{"post":{"tags":["Payment Charges"],"operationId":"refund-payment-charge","summary":"Refund a charge (full or partial). Operator/Pundit only — NEVER an autonomous bot action.","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":{"amount":{"type":"number","description":"Omit for a full refund."}}},"example":{"amount":149.9}}}},"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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"description":"Refund a charge (full or partial). Operator/Pundit only — NEVER an autonomous bot action. Submits the request payload to the Refund resource and returns the result."}},"/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","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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"description":"Cancel a pending charge at the gateway. Submits the request payload to the Cancel resource and returns the result."}},"/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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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)","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":{"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,"conversation_id":1,"crm_item_id":1,"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,"currency":"BRL","installments":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","gateway":"hotmart","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,"line_total":149.9,"currency":"BRL","position":1}]}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"description":"Send the charge into a conversation (rich card + PIX/boleto codes as separate copyable messages). Submits the request payload to the Send to conversation resource and returns the result."}},"/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"}}}}},"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"}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{"content":{"application/json":{"schema":{"type":"object","properties":{"charge":{"type":"object","properties":{"connection_id":{"type":"number","description":"Gateway connection; defaults to the account default."},"source":{"type":"string","enum":["manual","catalog","deal"],"default":"manual"},"amount":{"type":"number","description":"Major units (decimal). Ignored when source is catalog/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."}}}}},"example":{"charge":{"connection_id":1,"source":"manual","amount":149.9,"currency":"BRL","crm_item_id":1,"catalog_variant_ids":[1]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"currency":{"type":"string","description":"Settlement currency of the resolved connection."},"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","properties":{"catalog_variant_id":{"type":"number"},"name_snapshot":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"},"currency":{"type":"string"},"original_unit_price":{"type":["number","null"]},"original_currency":{"type":["string","null"]},"fx_rate":{"type":["number","null"]}}}}}}}},"example":{"payload":{"currency":"BRL","total":149.9,"original_amount":149.9,"original_currency":"sample original currency","fx_rate":12.5,"line_items":[{"catalog_variant_id":1,"name_snapshot":"sample name snapshot","quantity":12.5,"unit_price":149.9,"currency":"BRL","original_unit_price":149.9,"original_currency":"sample original currency","fx_rate":12.5}]}}}}},"422":{"description":"Unprocessable Entity (FX rate unavailable, or invalid source)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"422":{"description":"Unprocessable Entity (invalid ids or over the 500-id bulk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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,"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"}}}}}},"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},"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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}},"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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"]},"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"]},"association_status":{"type":["string","null"],"enum":["matched","unmatched",null],"description":"Payments subscription import-time verdict on the payer (Payments::DirectoryImportService, Payments::SubscriptionAdoptionService): `matched` linked a Contact, `unmatched` left contact_id blank because no gateway customer/e-mail/phone/document exact match was found. `null` for a manually-created subscription (it always carries a contact) or a row created before this key."}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","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","association_status":"matched"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}}}},"/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,"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"}}}}},"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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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,"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}},"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}}}},"/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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}},"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"}}}}},"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"}}}}}}},"/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"}}}}},"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"}}}},"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"}}}},"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"}}}}}},"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"}}}}},"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"}}}}},"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"}}}}},"401":{"description":"Unauthorized"}},"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"}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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"}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Calendar not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{},"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"}}}}}},"post":{"tags":["Calendar Events"],"operationId":"create-calendar-event","summary":"Create a calendar event","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"},"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"],"description":"An attendee's RSVP state for a calendar event."},"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,"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.","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"}}},"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":{},"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"}}}}},"201":{"description":"Created","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":{},"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"}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"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}}}}},"description":"Create a calendar event. Submits the request payload to the Events resource and returns the result."}},"/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":{},"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"}}}}},"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"},"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,"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":{},"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}}}}},"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"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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":"Successful response","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":"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"},"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":"An attendee's RSVP state for a calendar event."},"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":"sample all day","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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":"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"},"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"},"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":{"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":"sample all day","timezone":"America/Sao_Paulo","status":"confirmed","source":"native","contact_id":1,"conversation_id":1,"crm_item_id":1,"task_id":1,"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.","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"}}},"example":{"starts_at":"2026-01-15T10:30:00.000Z","ends_at":"2026-01-15T10:30:00.000Z"}}}},"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":{},"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"}}}},"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}}}}}}},"/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). An optional cancellation reason is persisted with the event and shared with the invitee.","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 and shared with the invitee."}},"example":{"reason":"Client requested a different day"}},"example":{"reason":"Client requested a different day"}}}},"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":{},"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"}}}}}}},"/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"}}}},"404":{"description":"Event or attendee not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"],"description":"An attendee's RSVP state for a calendar event."},"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"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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":{},"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"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"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}}}}}}},"/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"}}}}}},"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"}}}}}}},"/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"}}}}},"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"}}}}}},"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"}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"name":{"type":"string"},"slug":{"type":"string"},"duration_minutes":{"type":"integer"},"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_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"},"guest_emails_enabled":{"type":"boolean"},"max_guests":{"type":"string"},"host_user_ids":{"type":"array","items":{"type":"integer"}},"payment_billing_types":{"type":"array","items":{"type":"string"}},"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":{"name":"Sample Name","slug":"sample-slug","duration_minutes":60,"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_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,"guest_emails_enabled":true,"max_guests":"sample max guests","host_user_ids":[1],"payment_billing_types":["sample payment billing type"],"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"}}}}}}},"/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)","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":{"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"}}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}},"description":"Post the public booking URL into a conversation (Maestro calendar_send_booking_link). Submits the request payload to the Send link resource and returns the result."}},"/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"}}}},"422":{"description":"The event type must be archived before it can be purged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}}},"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"}}}}},"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"}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"422":{"description":"Country not selected, unsupported, or the holidays library is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}}}},"404":{"description":"Owner or inbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}}}}},"/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"}},"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"}}}}}},"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"}},"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"}},"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"}}}}}},"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"}},"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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"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"}}}}},"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"}}}}}}},"/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":{"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":{"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}}}},"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}}}},"404":{"description":"Event type not found in this account, or archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/bad_request_error"}}}},"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}}}}}}},"/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"}}}},"422":{"description":"Google OAuth is not configured on this installation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/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"}}}},"404":{"description":"Resource not found"}}}},"/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).","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","description":"The input type for the answer.","example":"text"},"required":{"type":"boolean","description":"Whether an answer is required.","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"},"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","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"},"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. Best-effort normalised to E.164 (a leading + or 00 and formatting characters are handled); a number that still fails validation, or that already belongs to another contact, is dropped without failing the booking. Gives the booking a WhatsApp destination for the confirmation and reminders.\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"},"answers":{"type":"object","description":"Visitor 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 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","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":{"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":{"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, policy violation (past the cancellation window, reschedule limit reached, a required phone number missing), 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 for a slot/policy refusal.","example":"slot no longer available"},"details":{"type":"object","description":"Present only for `needs_subscription` — how the visitor can subscribe.","additionalProperties":true}},"additionalProperties":false}}}},"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}}}}}}},"/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":{"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":{"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":{"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":{"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"}}}}}},"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":{"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":{"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"}}}}}},"404":{"description":"Booking not found"}}}},"/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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"/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)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"200":{"description":"Session revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}}}}},"/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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}},"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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}},"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."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"/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."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"/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."},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}},"/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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"302":{"description":"Redirect to the login page with the failure reason."}}}},"/auth/{provider}/callback":{"get":{"tags":["Authentication"],"operationId":"auto_get_auth_provider_callback","summary":"OAuth provider callback","description":"Completes the OmniAuth flow (e.g. google_oauth2) and redirects to the dashboard with a one-time sso_auth_token exchanged at POST /auth/sign_in.","security":[],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}]}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}},"/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":{"404":{"description":"The SDK module is unavailable because its build has not run for this deployment."},"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"}}}}}}},"/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 Chatwoot 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}}}}}},"422":{"description":"Unprocessable entity"},"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 account, PII or credential). 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":[],"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 across the fleet.\n# TYPE chatwoot_web_processes gauge\nchatwoot_web_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"}}},"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 9f2c1d7a4b6e8130a5c2f7e0d4b9a1c8"}}]}},"/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."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Cache keys accounts","description":"Performs the cache keys operation on the targeted account resource.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"cache_keys":{"type":"object","additionalProperties":true,"description":"Per-collection cache-key fingerprints used for client cache invalidation."}}},"example":{"cache_keys":{}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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":"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":"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"}}}}}},"404":{"description":"No account matches `account_id`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource could not be found"}}}}}},"422":{"description":"Unsupported bulk action type","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false}}}}}}},"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":"Ids of the records to act on (the page-level selection; ignored when select_all is true)","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":{"type":["string","null"],"format":"date-time","description":"Conversation bulk snooze target","example":null},"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}}}}},"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":null,"fields":{"status":"resolved","assignee_id":7,"team_id":2}}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"]}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The profile and its NEW bearer secret (shown ONCE).","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":"mcp_NEWsecret0PqRstuVwxyz1234567890abcdEFGH"}}},"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_NEWsecret0PqRstuVwxyz1234567890abcdEFGH"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator."},"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"}}}},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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).","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. `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 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":"The account members that can be a profile's acting user.","items":{"type":"object","properties":{"id":{"type":"integer","description":"User id.","example":5},"name":{"type":"string","description":"User display name.","example":"Alice Costa"}}}},"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},"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"},{"id":8,"name":"Bruno Dias"}],"cap":512,"oauth_enabled":true,"toolset_presets":[{"key":"essential","tags":["Conversations"]}],"chatgpt_compat_supported":true}}}},"401":{"description":"Unauthorized"},"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"}}}}},"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 toolset tags are dropped on write; the runtime re-intersects with the super-admin ceiling.","security":[{"userApiKey":[]}],"responses":{"201":{"description":"The created profile and its bearer secret (shown ONCE).","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":"mcp_kJ8s2n0PqRstuVwxyz1234567890abcdEFGHijkl"}}},"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_kJ8s2n0PqRstuVwxyz1234567890abcdEFGHijkl"}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator."},"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"}}}},"422":{"description":"Validation failed (e.g. blank name, or acting_user not a member of the account).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"array","description":"Human-readable validation messages.","items":{"type":"string","example":"Acting user must be a member of the account"}}}},"example":{"error":["Acting user must be a member of the account"]}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","acting_user_id"],"properties":{"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 ceiling-blocked tag can be stored but is never exposed. 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":{"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; the bearer secret is NOT touched (use rotate_token for that). Unknown toolset tags are dropped on write.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated profile.","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}}}}},"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}}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator."},"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"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"array","description":"Human-readable validation messages.","items":{"type":"string","example":"Acting user must be a member of the account"}}}},"example":{"error":["Acting user must be a member of the 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":{"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 tags dropped).","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,"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; the bearer secret is NOT touched (use rotate_token for that). Unknown toolset tags are dropped on write.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The updated profile.","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}}}}},"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}}}}},"401":{"description":"Missing or invalid access token, or the caller is not an account administrator."},"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"}}}},"422":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"array","description":"Human-readable validation messages.","items":{"type":"string","example":"Acting user must be a member of the account"}}}},"example":{"error":["Acting user must be a member of the 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":{"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 tags dropped).","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,"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.","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."},"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"}}}}},"parameters":[{"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}}},"example":{"generation_id":1,"state":"active","articles_count":0,"categories_count":0}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}/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.","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No account matches `account_id`."},"422":{"description":"Unprocessable entity"}},"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"}}},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"example":{"providers":"sample providers","models":"sample models","features":"sample features"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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/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"},"403":{"description":"Forbidden"},"404":{"description":"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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"},"403":{"description":"Forbidden"},"404":{"description":"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":"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."},"greeting_enabled":{"type":"boolean"},"greeting_message":{"type":"string"},"working_hours_enabled":{"type":"boolean"},"enable_email_collect":{"type":"string","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"inbox":{"type":"object","properties":{"inbox_id":{"type":"integer"}}}},"required":["inbox"]},"example":{"inbox":{"inbox_id":1}}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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":["pending","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":"pending","edited":"sample edited"}],"meta":{"total_count":5,"page":"sample page"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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_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":["pending","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":"pending","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"status":{"type":"string","enum":["pending","approved"]}},"required":["answer","question"]}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1,"status":"pending"}}}}}}},"/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":["pending","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":"pending","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":["pending","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":"pending","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"status":{"type":"string","enum":["pending","approved"]}}}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1,"status":"pending"}}}}}},"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":["pending","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":"pending","edited":"sample edited"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"status":{"type":"string","enum":["pending","approved"]}}}},"required":["assistant_response"]},"example":{"assistant_response":{"question":"sample question","answer":"sample answer","assistant_id":1,"status":"pending"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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/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":["pending","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":"pending","edited":"sample edited"}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"fields":{"type":"string"}}},"example":{"type":"sample type","ids":"sample ids","fields":"sample fields"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Create copilot threads","description":"Creates a new copilot thread 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"assistant_id":{"type":"integer"},"conversation_id":{"type":"integer"}}},"example":{"message":"Sample message text.","assistant_id":1,"conversation_id":1}}}}}},"/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":{"type":"object","properties":{"status":{"type":"integer","example":200},"body":{"type":"string"}}},"example":{"status":200,"body":"Sample body text."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"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":{"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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","account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"action":{"type":"string"}}},"example":{"action":"sample action"}}}}}},"/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"},"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","account_id":1,"access_token":"sample-token","secret":"sample-token","system_bot":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"action":{"type":"string"}}},"example":{"action":"sample action"}}}}}},"/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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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, and the linked AgentBot's webhook secret is pushed so the first delivery already verifies. Only the fields documented here are forwarded to the Maestro sidecar - anything else in the payload is discarded.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."},"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"}}}},"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"}}}},"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"}}}},"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_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","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"}}}}},"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":"Agent name, unique within the account. Also names the linked 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_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","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 Chatwoot-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 + Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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_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","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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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_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","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_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","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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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_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","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 Chatwoot round-trip — every reference is then reported as cleared, so an import still works when Chatwoot 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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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_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","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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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_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","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}/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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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. Chatwoot never persists the plaintext, so it cannot be recovered later — copy it into the external MCP client now. Takes no request body. Admin-only.","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.","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The plaintext bearer token. Shown only in this response, never again.","example":"8bZq2Vx7Kp-Rn4sT1uW9yA0cE3gH6jL8mN2pQ5rS7t"},"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":"8bZq2Vx7Kp-Rn4sT1uW9yA0cE3gH6jL8mN2pQ5rS7t","endpoint_url":"https://maestro.example.com/mcp","endpoint_public":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"503":{"description":"Maestro is not configured for this installation, or the sidecar is unreachable. Nothing was rotated — any previously issued token remains valid.","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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 Chatwoot. `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":"sk-proj-0123456789abcdef"},"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":"sk-proj-0123456789abcdef","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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 Chatwoot. 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"No Robô with this id belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"No Robô with this id belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"No Robô with this id belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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}/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"},"403":{"description":"Forbidden"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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, Chatwoot also carries the stored `standdown_auto_resume` and `standdown_ttl_seconds` through a partial payload; a legacy null/missing value resolves to the shipped policy (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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."},"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"}}}},"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"}}}},"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"}}}}},"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":"Inbox links to apply.","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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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 two human-takeover fields are protected from that replacement hazard: when omitted/null, Chatwoot preserves the stored `standdown_auto_resume` and `standdown_ttl_seconds`; a legacy null/missing stored value resolves to 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_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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."},"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"}}}},"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"}}}},"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"}}}}},"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_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","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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No Robô with this id belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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_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","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"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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"},"403":{"description":"Forbidden"},"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"}}}},"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"}}}},"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"}}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No Robô with this id belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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":"array","items":{"type":"string"}}}}}}},"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 tag"]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"article_ids":"sample article ids"}}}}}},"/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_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 Chatwoot 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":"Chatwoot's authoritative local projection. `unknown` is held fail-closed and must never be interpreted as active.","example":"paused"},"human_assigned":{"type":"boolean","description":"Chatwoot's tenant-scoped assignment fence. True keeps Resume unavailable and the authoritative local projection paused, regardless of a stale remote flag.","example":true},"maestro_binding_mismatch":{"type":"boolean","description":"True when Chatwoot 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},"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}}},"example":{"contract_version":"2","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","human_assigned":true,"maestro_binding_mismatch":false,"paused_inbound_retained_count":3,"paused_inbound_replay_available":false,"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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"]}}}}}}},"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"400":{"description":"Unknown picker kind.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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}}}}},"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}}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"query","required":false,"description":"Restrict the pending approvals to one conversation. Omitted, every pending item of the account is listed.","schema":{"type":"integer"},"example":4821}]}},"/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. An action whose re-run fails is KEPT parked so it can be retried, and the response says so: `ok` is false with the failure in `detail`, rather than the action being silently marked approved. The same `ok: false` shape reports an identifier that no longer exists, which is what a second click on an already-resolved action produces.","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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cmd":{"type":"string"},"conversation_id":{"type":"integer"}}},"example":{"cmd":"sample cmd","conversation_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},"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cmd":{"type":"string"},"conversation_id":{"type":"integer"}}},"example":{"cmd":"sample cmd","conversation_id":1}}}}}},"/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. Chatwoot 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.","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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Confirmation, conversation id or the UUID idempotency identifier is missing or invalid."},"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"}}}},"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"}}}},"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"}}}},"409":{"description":"The conversation is still paused, unknown or assigned to a human; nothing was released."}},"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}}},"example":{"conversation_id":4821,"request_id":"76d70ec8-fe05-43b1-8a1f-d2bb4cc7ad49","confirm":true}}}}}},"/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":"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. Chatwoot 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 Chatwoot 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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"503":{"description":"The Maestro feature is disabled or not configured, or Chatwoot 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.","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"]}}}}}},"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"]}}}}}},"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 Chatwoot 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"]}}}}}}},"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":"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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/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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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":"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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/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":"Answers a free-form question using read-only tools over the account's data, plus 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.","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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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/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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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/copilot/execute":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_copilot_execute","summary":"Run a confirmed copilot action card","description":"Runs the single write tool behind a proposal card, after a human confirmed it in the panel. 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 call runs under the requesting user so native permissions still apply. The response echoes who ran it, for the audit trail. A 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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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."}},"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"}}}},"example":{"conversation_id":4821,"tool":"generate_image","args":{"prompt":"Promotional image of the winter combo, warm lighting","caption":"Nosso combo de inverno"}}}}}}},"/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":"Renders the image, voice note or video a card proposed, WITHOUT sending it, 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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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":"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"preview_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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":"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string"}}},"example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"An assignment names an unknown surface, or a Robô from another 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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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.","enum":["passed","softened","stripped","regenerated","held","blocked","judge_flagged"],"example":"passed"},"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":"How many of those calls did not succeed.","example":0},"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","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":0,"claims_flagged":0,"judge_score":0.94,"resolved_at":null,"resolved_by":null}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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.","enum":["passed","softened","stripped","regenerated","held","blocked","judge_flagged"],"example":"passed"},"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":"How many of those calls did not succeed.","example":0},"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 checks fired on this reply and what each decided. Keys are check names; values are the per-check verdicts.","additionalProperties":true,"example":{"pii":"clean","banned_topics":"clean"}},"claims":{"type":"object","description":"The reconciliation outcome: which statements in the reply were backed by tool evidence and which were not. Empty when the turn made no checkable claim.","additionalProperties":true,"example":{"checked":3,"flagged":[]}},"evidence_digest":{"type":"object","description":"Which tools ran and how each ended. Names and statuses only - never their arguments or results, so the audit trail is not a second copy of customer data.","additionalProperties":true,"example":{"tools":[{"name":"commerce_find_order","status":"ok"}]}},"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 the human decided, and whether it took effect. `failed` is a decision that did NOT land - the approved action errored and stayed parked - which is recorded precisely because it is the event someone later asks about.","enum":["approved","rejected","failed"],"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"},"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","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":0,"claims_flagged":0,"judge_score":0.94,"resolved_at":null,"resolved_by":null,"locale":"pt_BR","classes":{"pii":"clean","banned_topics":"clean"},"claims":{"checked":3,"flagged":[]},"evidence_digest":{"tools":[{"name":"commerce_find_order","status":"ok"}]},"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","detail":"Negócio criado no CRM.","created_at":"2026-07-27T14:05:02Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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"}}}},"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"}}}},"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"}}}}},"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 the human decided, and whether it took effect. `failed` is a decision that did NOT land - the approved action errored and stayed parked - which is recorded precisely because it is the event someone later asks about.","enum":["approved","rejected","failed"],"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"},"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","detail":"Negócio criado no CRM.","created_at":"2026-07-27T14:05:02Z"}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"No Robô is bound to this account, so there is nothing to apply the policy to. Nothing was stored."},"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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":"Insights brain","description":"Performs the insights 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"},"insight_type":{"type":"string"},"severity":{"type":"string","enum":["info","low","medium","high","critical"],"description":"Severity of the brain insight."},"subject_type":{"type":"string"},"subject_id":{"type":"integer"},"title":{"type":"string"},"body":{"type":"string"},"suggested_action":{"type":"string"},"sensitive":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"string"}}},"example":{"payload":[{"id":1,"department":"sample department","insight_type":"sample insight type","severity":"info","subject_type":"sample subject type","subject_id":1,"title":"Sample title","body":"Sample body text.","suggested_action":"sample suggested action","sensitive":"sample sensitive","created_at":"2026-01-15T10:30:00.000Z"}],"meta":"sample meta"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/maestro/brain/risk":{"get":{"tags":["Maestro"],"operationId":"auto_get_api_v1_accounts_account_id_maestro_brain_risk","summary":"Risk brain","description":"Performs the risk 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"},"subject_type":{"type":"string"},"subject_id":{"type":"integer"},"score":{"type":"string"},"band":{"type":"string"},"signals":{"type":"string"},"computed_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"subject_type":"sample subject type","subject_id":1,"score":"sample score","band":"sample band","signals":"sample signals","computed_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"string"}}},"example":{"payload":[{}],"meta":"sample meta"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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 recommendation brain","description":"Performs the accept recommendation 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":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}},"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":{"note":{"type":"string"}}},"example":{"note":"Sample note."}}}}}},"/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 recommendation brain","description":"Performs the reject recommendation 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":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}},"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":{"note":{"type":"string"}}},"example":{"note":"Sample note."}}}}}},"/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` alongside the total instead of letting a by-model chart quietly sum to less than the invoice.\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 `cost_usd` beside it is a FLOOR, not a total, and a client that renders the two without the other is publishing a number smaller than the invoice.","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","properties":{"conversation_id":{"type":"integer","description":"Chatwoot 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","format":"float","description":"Cost in USD for this conversation, both sides summed.","example":0.0184},"unpriced_calls":{"type":"integer","description":"Calls here whose cost is NOT a measurement. Above zero means `cost_usd` is a floor rather than a total.","example":2},"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":"How much of this row's `cost_usd` carries a model label. Below `cost_usd` means conversation turns contributed cost no model can be placed against.","example":0.0041},"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":"How much of `cost_usd` was spent by delegated or summary work rather than by the turn itself. A SUBSET of `cost_usd`, never an addition — it answers \"was the delegation billed to the right conversation?\". NULL means not measured, never zero.","example":0.0052},"nested_truncated":{"type":"boolean","description":"True when the nested scan hit its row cap, so `nested_calls` and `nested_cost_usd` are null rather than a floor. The top-level `nested` block still carries the delegation story for the whole window.","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","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","format":"float","description":"Cost in USD that day.","example":0.0451}}}},"model_attributed_cost_usd":{"type":"number","format":"float","description":"How much of `totals.cost_usd` carries a model label. Below the total means conversation turns contributed cost the by-model breakdown cannot place.","example":0.0076},"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: real, priced, and ALREADY INSIDE `totals` because it is booked on the parent turn. Reported separately because the alternative is silence — a delegation adds nothing to any bucket by design, so without this block one that cost real money is indistinguishable from one that never happened. A breakdown, never an addition: adding these figures to `totals` double-counts them. That is the opposite hazard from `unpriced`, which is why the two are different shapes rather than one flag.","properties":{"calls":{"type":"integer","description":"Nested model calls in the window, after filters.","example":18},"cost_usd":{"type":"number","format":"float","description":"What that nested work cost. ALREADY counted in `totals.cost_usd` — never add it on top.","example":0.0219},"rows":{"type":"integer","description":"Nested spend records behind those calls. Exact — counted in SQL.","example":18},"truncated":{"type":"boolean","description":"True when there were more nested records than this roll-up reads, so `calls` and `cost_usd` are a floor. `rows` stays exact.","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","format":"float","description":"What it really cost. Already inside `totals` via the parent turn.","example":0.0161},"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":"Suporte Nível 1","calls":10,"input_tokens":800,"output_tokens":100,"cache_read_tokens":380,"cost_usd":0.0375,"unpriced_calls":2},"by_surface":[{"key":"turn","label":"Suporte Nível 1","calls":10,"input_tokens":800,"output_tokens":100,"cache_read_tokens":380,"cost_usd":0.0375,"unpriced_calls":2}],"by_model":[{"key":"turn","label":"Suporte Nível 1","calls":10,"input_tokens":800,"output_tokens":100,"cache_read_tokens":380,"cost_usd":0.0375,"unpriced_calls":2}],"by_agent":[{"key":"turn","label":"Suporte Nível 1","calls":10,"input_tokens":800,"output_tokens":100,"cache_read_tokens":380,"cost_usd":0.0375,"unpriced_calls":2}],"by_conversation":[{"conversation_id":1042,"calls":14,"turns":9,"input_tokens":6200,"output_tokens":940,"cache_read_tokens":2100,"cost_usd":0.0184,"unpriced_calls":2,"model":"gpt-5.4-mini-2026-03-17","model_attributed_cost_usd":0.0041,"nested_calls":3,"nested_cost_usd":0.0052,"nested_truncated":false}],"daily":[{"date":"2026-08-01","calls":12,"cost_usd":0.0451}],"model_attributed_cost_usd":0.0076,"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":18,"cost_usd":0.0219,"rows":18,"truncated":false,"surfaces":[{"key":"delegation","calls":12,"cost_usd":0.0161,"rows":12}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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/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","null"]},"status":{"type":"string","example":"draft"},"transcript":{"type":"array","items":{"type":"string"}},"proposal":{"type":"object","additionalProperties":true,"description":"Free-form object."},"applied_agent_bot_id":{"type":["integer","null"]}}},"example":{"id":1,"status":"draft","transcript":["sample transcript"],"proposal":{},"applied_agent_bot_id":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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":"string"}}},"example":{"message":"Sample message text.","locale":"en","transcript":"sample transcript"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"locale":"en","transcript":"sample transcript"}}}}}},"/api/v1/accounts/{account_id}/maestro/onboarding/apply":{"post":{"tags":["Maestro"],"operationId":"auto_post_api_v1_accounts_account_id_maestro_onboarding_apply","summary":"Apply the reviewed Maestro onboarding proposal","description":"Forwards the operator-reviewed RobotProposal verbatim to the sidecar, which seeds the KB and creates/updates an AgentBot; on success the native briefing row is marked applied and linked. Admin-only. The proposal may have been edited by the operator in the review step.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"sample error"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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}}},"example":{"proposal":{"persona":"Friendly support assistant","instructions":"Answer product questions in pt_BR."},"agent_bot_id":42}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Only administrators can resolve a parked run."},"404":{"description":"No run with this identifier belongs to the account."},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}},"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"},"403":{"description":"Only administrators can change department settings."},"404":{"description":"Resource not found"},"422":{"description":"The autonomy tier is not one of the three accepted values. Nothing was stored."},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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/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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"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":{"spec":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"spec":{}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Only administrators can feed the account brain."},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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."}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Returns the list of assignable agents 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","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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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}/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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.","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"},"403":{"description":"Forbidden"},"404":{"description":"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.","schema":{"type":"string","example":"conversation"}},{"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":{"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"},"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,"files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"]},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"]},"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","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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"account_id":1,"actions":"sample actions","files":"sample files"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"],"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"],"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"],"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"],"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"],"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":"object","properties":{"access_token":{"type":"string"},"account_id":{"type":["integer","null"]},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"email":{"type":"string","format":"email"},"hmac_identifier":{"type":"string"},"id":{"type":"integer"},"inviter_id":{"type":["integer","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"pubsub_token":{"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, ...)."},"role":{"type":["string","null"],"enum":["agent","administrator",null]},"ui_settings":{"type":"string"},"uid":{"type":"string"},"type":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"onboarding_step":{"type":"string"},"active_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["agent","administrator"]},"permissions":{"type":"string"},"access_role_id":{"type":["integer","null"]},"access_role":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"type":"string"}}}}}}}}},"example":[{"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","id":1,"inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","custom_attributes":{},"role":"agent","ui_settings":"sample ui settings","uid":"sample uid","type":"sample type","accounts":[{"id":1,"name":"Sample Name","status":"active","onboarding_step":"sample onboarding step","active_at":"2026-01-15T10:30:00.000Z","role":"agent","permissions":"sample permissions","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":"sample field permissions"}}]}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":"object","properties":{"access_token":{"type":"string"},"account_id":{"type":["integer","null"]},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"email":{"type":"string","format":"email"},"hmac_identifier":{"type":"string"},"id":{"type":"integer"},"inviter_id":{"type":["integer","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"The authentication provider the user account was created with."},"pubsub_token":{"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, ...)."},"role":{"type":["string","null"],"enum":["agent","administrator",null]},"ui_settings":{"type":"string"},"uid":{"type":"string"},"type":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"onboarding_step":{"type":"string"},"active_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["agent","administrator"]},"permissions":{"type":"string"},"access_role_id":{"type":["integer","null"]},"access_role":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"type":"string"}}}}}}}},"example":{"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","id":1,"inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","custom_attributes":{},"role":"agent","ui_settings":"sample ui settings","uid":"sample uid","type":"sample type","accounts":[{"id":1,"name":"Sample Name","status":"active","onboarding_step":"sample onboarding step","active_at":"2026-01-15T10:30:00.000Z","role":"agent","permissions":"sample permissions","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":"sample field permissions"}}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_limit":{"type":"string"}}},"example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_limit":{"type":"string"}}},"example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_limit":{"type":"string"}}},"example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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. Answers `200 OK` with the updated campaign, so the caller reads the resulting `campaign_status` straight from the response. A campaign in any other state is no longer a silent no-op sharing the success response: it is refused with `422`, and the body names the `campaign_status` that blocked the transition.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Campaign paused. Body is the updated campaign."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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":"Flips a paused campaign back to sending and re-schedules every recipient still pending, honouring the configured anti-block delays; already dispatched or terminal recipients are left alone. If nothing remains pending the campaign is finalized instead. Answers `200 OK` with the campaign as it stands after the run, so the caller reads the resulting status without a second request. Only a PAUSED campaign can be resumed — any other state is refused with `422` instead of the empty success the service's own `return unless campaign.paused?` guard used to produce.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Resume processed. Body is the campaign after the pending recipients were re-scheduled."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No campaign with this display id in the account."},"422":{"description":"The campaign was not paused, so there is nothing to resume. Body is `{ \"error\": \"not_resumable\", \"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}/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. Answers `200 OK` with the campaign after the cancellation, so the resulting status and recipient breakdown come back in the response. Only a campaign in `draft`, `scheduled`, `sending` or `paused` can be cancelled (the service's own CANCELLABLE_STATUSES); anything else — an already completed campaign, typically — is refused with `422` rather than answering like a successful cancellation.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Cancellation processed. Body is the campaign after the pending recipients were skipped."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"}}},"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"},"conversation_id":{"type":"integer"},"message_id":{"type":"integer"},"sent_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"read_at":{"type":"string","format":"date-time"},"replied_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"cost":{"type":"string"},"cost_basis":{"type":"string"},"priced_at":{"type":"string","format":"date-time"}}}}}},"example":{"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages"},"payload":[{"id":1,"status":"pending","error":"sample error","conversation_id":1,"message_id":1,"sent_at":"2026-01-15T10:30:00.000Z","delivered_at":"2026-01-15T10:30:00.000Z","read_at":"2026-01-15T10:30:00.000Z","replied_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","cost":"sample cost","cost_basis":"sample cost basis","priced_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 campaigns","description":"Performs the retry 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":{"retried":{"type":"string"},"recipient_stats":{"type":"string"}}},"example":{"retried":"sample retried","recipient_stats":"sample recipient stats"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"recipient_ids":"sample recipient ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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","example":"2026-06-01"},"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-06-01","synced_at":null}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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 sync outcome 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":"RateCardSyncService result — { ok:true, countries, source, synced_at } or { ok:false, reason }","properties":{"ok":{"type":"boolean","example":false},"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"],"example":"no_rates_parsed"}}}}},"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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Number of resolved (phone-bearing) contacts","example":1280},"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},"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,"consent_excluded_count":12,"estimated_cost":80.0,"currency":"BRL","billable":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"When present, also returns the estimated BRL cost","example":"marketing"},"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}}},"example":{"audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"category":"marketing","provider":"whatsapp_cloud","require_phone":true}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"blob":{"type":"string"}}},"example":{"blob":"sample blob"}}}}}},"/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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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"]},"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"},"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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","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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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 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":"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":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"},"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","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":{},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"title":{"type":"string"},"description":{"type":"string"},"message":{"type":"string"},"enabled":{"type":"boolean"},"trigger_only_during_business_hours":{"type":"string"},"inbox_id":{"type":"integer"},"sender_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"scheduled_at":{"type":"string","format":"date-time"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"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":"object","additionalProperties":true,"description":"Free-form object."},"template_params":{"type":"object","additionalProperties":true,"description":"Free-form object."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"required":["inbox_id","message","title"]}},"required":["campaign"]},"example":{"campaign":{"title":"Sample title","description":"A short description.","message":"Sample message text.","enabled":true,"trigger_only_during_business_hours":"sample trigger only during business hours","inbox_id":1,"sender_id":1,"whatsapp_transport":"sample whatsapp transport","scheduled_at":"2026-01-15T10:30:00.000Z","campaign_status":"active","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"template_params":{},"send_settings":{}}}}}}}},"/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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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"]},"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"},"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"},"recipient_timing":{"type":"string"}}},"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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","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,"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","recipient_timing":"sample recipient timing"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 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":"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":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"},"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","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":{},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"title":{"type":"string"},"description":{"type":"string"},"message":{"type":"string"},"enabled":{"type":"boolean"},"trigger_only_during_business_hours":{"type":"string"},"inbox_id":{"type":"integer"},"sender_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"scheduled_at":{"type":"string","format":"date-time"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"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":"object","additionalProperties":true,"description":"Free-form object."},"template_params":{"type":"object","additionalProperties":true,"description":"Free-form object."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["campaign"]},"example":{"campaign":{"title":"Sample title","description":"A short description.","message":"Sample message text.","enabled":true,"trigger_only_during_business_hours":"sample trigger only during business hours","inbox_id":1,"sender_id":1,"whatsapp_transport":"sample whatsapp transport","scheduled_at":"2026-01-15T10:30:00.000Z","campaign_status":"active","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"template_params":{},"send_settings":{}}}}}}},"put":{"tags":["Campaigns"],"operationId":"auto_put_api_v1_accounts_account_id_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":"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":{"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","business_name":"sample business name","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","medium":"sample medium","provider":"default"},"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","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":{},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"title":{"type":"string"},"description":{"type":"string"},"message":{"type":"string"},"enabled":{"type":"boolean"},"trigger_only_during_business_hours":{"type":"string"},"inbox_id":{"type":"integer"},"sender_id":{"type":"integer"},"whatsapp_transport":{"type":"string"},"scheduled_at":{"type":"string","format":"date-time"},"campaign_status":{"type":"string","enum":["active","completed","draft","scheduled","sending","paused","failed","processing"]},"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":"object","additionalProperties":true,"description":"Free-form object."},"template_params":{"type":"object","additionalProperties":true,"description":"Free-form object."},"send_settings":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["campaign"]},"example":{"campaign":{"title":"Sample title","description":"A short description.","message":"Sample message text.","enabled":true,"trigger_only_during_business_hours":"sample trigger only during business hours","inbox_id":1,"sender_id":1,"whatsapp_transport":"sample whatsapp transport","scheduled_at":"2026-01-15T10:30:00.000Z","campaign_status":"active","audience":[{"type":"Label","id":15,"source":"conversation","conversation_status":"open","stage_id":21}],"trigger_rules":{},"template_params":{},"send_settings":{}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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/{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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"403":{"description":"Forbidden"},"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"}}}},"403":{"description":"Forbidden"},"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"}}}},"403":{"description":"Forbidden"},"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"}}}},"403":{"description":"Forbidden"},"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 Chatwoot 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"}}}},"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"}}}},"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"}}}},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"}}}},"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"}}}},"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"}}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}},"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"}}}}},"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"}}}},"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"}}}},"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"}}}}},"parameters":[{"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/{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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"reporter_last_read_at":{"type":["integer","null"]},"unread_count":{"type":"integer"}}},"example":{"reporter_last_read_at":1,"unread_count":5}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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"],"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.","system_key":"message_retracted","origin":"local","client_uuid":"sample client uuid","delivery_state":"pending","created_at":1,"external_created_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bug_report_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_uuid":{"type":"string"},"content":{"type":"string"}}},"example":{"client_uuid":"sample client uuid","content":"Sample content text."}}}}}},"/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."},"status_source":{"type":"string","enum":["local","central"],"description":"Where `effective_status` came from (BugReport#status_source). `local` means it is this report's own recorded `status`; `central` means a terminal verdict from the central support triage is being displayed because the report's own status is still a filing state."},"messages_count":{"type":"integer"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"string"},"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","status_source":"local","messages_count":5,"thread_unread":true,"synced_at":1,"attachments":"sample attachments","created_at":1,"updated_at":1}],"meta":{"count":5,"current_page":"sample current page"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}]},"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."},"status_source":{"type":"string","enum":["local","central"],"description":"Where `effective_status` came from (BugReport#status_source). `local` means it is this report's own recorded `status`; `central` means a terminal verdict from the central support triage is being displayed because the report's own status is still a filing state."},"messages_count":{"type":"integer"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"string"},"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","status_source":"local","messages_count":5,"thread_unread":true,"synced_at":1,"attachments":"sample attachments","created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."},"status_source":{"type":"string","enum":["local","central"],"description":"Where `effective_status` came from (BugReport#status_source). `local` means it is this report's own recorded `status`; `central` means a terminal verdict from the central support triage is being displayed because the report's own status is still a filing state."},"messages_count":{"type":"integer"},"thread_unread":{"type":"boolean"},"synced_at":{"type":["integer","null"]},"attachments":{"type":"string"},"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","status_source":"local","messages_count":5,"thread_unread":true,"synced_at":1,"attachments":"sample attachments","created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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. Reporting the runaway outcome additionally disables the script durably, so it stops being served and cannot re-inject on the next page load. The endpoint always returns an EMPTY body — HTTP 200 whether the report was 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"},"403":{"description":"Forbidden"},"404":{"description":"No custom script with this id exists. Empty body."},"422":{"description":"Unprocessable entity"}},"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 runaway value is not stored as such: it is recorded as an error and durably disables the script.","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"},"403":{"description":"Forbidden"},"404":{"description":"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 twilio channels","description":"Creates a new twilio channel 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"},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"api_key_sid":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"messaging_service_sid":{"type":"string"},"name":{"type":"string"}}},"example":{"api_key_sid":"sample api key sid","auth_token":"sample-token","account_sid":"sample account sid","messaging_service_sid":"sample messaging service sid","name":"Sample Name"}}}}}},"/api/v1/accounts/{account_id}/conversations/search":{"get":{"tags":["Conversations"],"operationId":"auto_get_api_v1_accounts_account_id_conversations_search","summary":"Search conversations","description":"Performs the search 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":{"mine_count":{"type":"integer"},"unassigned_count":{"type":"integer"},"all_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"}}}},"account_id":{"type":"integer"}}}}}},"example":{"meta":{"mine_count":5,"unassigned_count":5,"all_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"}],"account_id":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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."},"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"},"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":"object","properties":{"id":{"type":"integer"},"sla_id":{"type":"integer"},"sla_status":{"type":"string","enum":["active","hit","missed","active_with_misses"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"sla_description":{"type":"string"},"sla_name":{"type":"string"},"sla_first_response_time_threshold":{"type":"string"},"sla_next_response_time_threshold":{"type":"string"},"sla_only_during_business_hours":{"type":"string"},"sla_resolution_time_threshold":{"type":"string"}}},"sla_events":{"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"}}}}}}}}},"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","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,"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,"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":{"id":1,"sla_id":1,"sla_status":"active","created_at":1,"updated_at":1,"sla_description":"sample sla description","sla_name":"sample sla name","sla_first_response_time_threshold":"sample sla first response time threshold","sla_next_response_time_threshold":"sample sla next response time threshold","sla_only_during_business_hours":"sample sla only during business hours","sla_resolution_time_threshold":"sample sla resolution time threshold"},"sla_events":[{"id":1,"event_type":"frt","meta":"sample meta","updated_at":1,"created_at":1}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Authenticated user cannot view this conversation"},"404":{"description":"Feature disabled or conversation 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_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"},"403":{"description":"User cannot manage translation settings for this conversation"},"404":{"description":"Feature disabled or conversation not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}}},"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"},"403":{"description":"Authenticated user cannot view this conversation, or caller is non-human"},"404":{"description":"Feature disabled or conversation not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}},"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"]}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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/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, reusing the original attachments (no re-upload). 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, interactive types) are rejected with 422. 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":true},"forwarded_message_ids":{"type":"array","description":"Ids of the copies created in the target (partial on send_failed).","items":{"type":"integer"},"example":[9921,9922]},"error_code":{"type":"string","description":"Present only when success is false.","enum":["unauthorized","target_is_source","target_unavailable","not_found","send_failed"],"example":"unauthorized"}}}}}},"example":{"results":[{"conversation_id":212,"success":true,"forwarded_message_ids":[9921,9922],"error_code":"unauthorized"},{"conversation_id":305,"success":false,"forwarded_message_ids":[],"error_code":"unauthorized"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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,4583]},"target_conversation_ids":{"type":"array","description":"Display ids of the target conversations (1..5).","items":{"type":"integer"},"example":[212,305]}}},"example":{"message_ids":[4581,4583],"target_conversation_ids":[212,305]}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"No message with this id exists in the conversation."},"422":{"description":"Unprocessable entity"}},"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 messages","description":"Performs the retry 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":{"id":{"type":"integer"},"content":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"echo_id":{"type":"integer"},"conversation_id":{"type":"integer"},"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"]},"status":{"type":"string","enum":["sent","delivered","read","failed"]},"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"},"private":{"type":"string"},"source_id":{"type":"integer"},"sender":{"type":"string"},"attachments":{"type":"array","items":{"type":"string"}},"set":{"type":"string"}}},"example":{"id":1,"content":"Sample content text.","inbox_id":1,"logical_inbox_id":1,"echo_id":1,"conversation_id":1,"message_type":"incoming","content_type":"text","status":"sent","content_attributes":{},"created_at":1,"private":"sample private","source_id":1,"sender":"sample sender","attachments":["sample attachment"],"set":"sample set"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"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."}}},"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"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/{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"},"403":{"description":"Forbidden"},"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"}}}},"422":{"description":"Unprocessable entity"}},"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"}}},"example":{"transcription":"sample transcription","transcription_error":"sample transcription error"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"transcription":{"type":"string"}}},"example":{"transcription":"sample transcription"}}}}}},"/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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"user_ids":"sample user ids"}}}}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"user_ids":"sample user ids"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"user_ids":"sample user ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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":{"type":"object","properties":{"has_draft":{"type":"boolean","example":false}}},"example":{"has_draft":false}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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 calls","description":"Returns the list of calls 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"},"403":{"description":"Forbidden"},"404":{"description":"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/{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"},"403":{"description":"Forbidden"},"404":{"description":"No conversation with this display id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"No conversation with this display id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"No conversation with this display id exists in the account."},"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"}}}},"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"}}}},"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"]},"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."},"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"},"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":"object","properties":{"id":{"type":"integer"},"sla_id":{"type":"integer"},"sla_status":{"type":"string","enum":["active","hit","missed","active_with_misses"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"sla_description":{"type":"string"},"sla_name":{"type":"string"},"sla_first_response_time_threshold":{"type":"string"},"sla_next_response_time_threshold":{"type":"string"},"sla_only_during_business_hours":{"type":"string"},"sla_resolution_time_threshold":{"type":"string"}}},"sla_events":{"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"}}}}}},"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","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,"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,"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":{"id":1,"sla_id":1,"sla_status":"active","created_at":1,"updated_at":1,"sla_description":"sample sla description","sla_name":"sample sla name","sla_first_response_time_threshold":"sample sla first response time threshold","sla_next_response_time_threshold":"sample sla next response time threshold","sla_only_during_business_hours":"sample sla only during business hours","sla_resolution_time_threshold":"sample sla resolution time threshold"},"sla_events":[{"id":1,"event_type":"frt","meta":"sample meta","updated_at":1,"created_at":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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."},"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"},"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":"object","properties":{"id":{"type":"integer"},"sla_id":{"type":"integer"},"sla_status":{"type":"string","enum":["active","hit","missed","active_with_misses"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"sla_description":{"type":"string"},"sla_name":{"type":"string"},"sla_first_response_time_threshold":{"type":"string"},"sla_next_response_time_threshold":{"type":"string"},"sla_only_during_business_hours":{"type":"string"},"sla_resolution_time_threshold":{"type":"string"}}},"sla_events":{"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"}}}}}},"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","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,"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,"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":{"id":1,"sla_id":1,"sla_status":"active","created_at":1,"updated_at":1,"sla_description":"sample sla description","sla_name":"sample sla name","sla_first_response_time_threshold":"sample sla first response time threshold","sla_next_response_time_threshold":"sample sla next response time threshold","sla_only_during_business_hours":"sample sla only during business hours","sla_resolution_time_threshold":"sample sla resolution time threshold"},"sla_events":[{"id":1,"event_type":"frt","meta":"sample meta","updated_at":1,"created_at":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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."},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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."},"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"},"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":"object","properties":{"id":{"type":"integer"},"sla_id":{"type":"integer"},"sla_status":{"type":"string","enum":["active","hit","missed","active_with_misses"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"},"sla_description":{"type":"string"},"sla_name":{"type":"string"},"sla_first_response_time_threshold":{"type":"string"},"sla_next_response_time_threshold":{"type":"string"},"sla_only_during_business_hours":{"type":"string"},"sla_resolution_time_threshold":{"type":"string"}}},"sla_events":{"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"}}}}}}}}},"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","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,"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,"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":{"id":1,"sla_id":1,"sla_status":"active","created_at":1,"updated_at":1,"sla_description":"sample sla description","sla_name":"sample sla name","sla_first_response_time_threshold":"sample sla first response time threshold","sla_next_response_time_threshold":"sample sla next response time threshold","sla_only_during_business_hours":"sample sla only during business hours","sla_resolution_time_threshold":"sample sla resolution time threshold"},"sla_events":[{"id":1,"event_type":"frt","meta":"sample meta","updated_at":1,"created_at":1}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":"object","properties":{"payload":{"type":"object","additionalProperties":true,"description":"Free-form object."}}},"example":{"payload":{}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"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"}}}}}},"404":{"description":"No account matches `account_id`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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}/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."},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Create calls","description":"Creates a new call 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":{"conversation_id":{"type":"integer"},"inbox_id":{"type":"integer"},"call_sid":{"type":"string"},"conference_sid":{"type":"string"}}},"example":{"conversation_id":1,"inbox_id":1,"call_sid":"sample call sid","conference_sid":"sample conference sid"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"conversation_id":{"type":"integer"}}},"example":{"inbox_id":1,"conversation_id":1}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":["object","null"],"description":"Contact model (present when linked)."},"conversation_id":{"type":"integer","description":"Conversation display id.","example":812},"assigned_agent":{"type":["object","null"],"description":"Assigned agent (id, name, email, available_name, role) when present."},"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":{},"conversation_id":812,"assigned_agent":{},"created_at":1736850600}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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_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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."}}}},"403":{"description":"Forbidden"},"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"}}}},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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.","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"},"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."}}}},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}}},"example":{"client_session_id":"01913dd8-8e85-75fd-9e0f-fb52127a79a0","claim_token":"1vXQW9w5y-X5JjzPvQdV2D_mEPsSyF4PiuMrp53Dd8A","expected_revision":1}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Claim expired, is missing, or belongs to another agent tab."},"404":{"description":"Resource not found"},"422":{"description":"pre_accept is missing/mismatched, or Meta definitively rejected signaling."},"409":{"description":"Lifecycle revision is stale or a competing tab owns the call."}},"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"},"403":{"description":"Agent is outside the audience or the claim is not valid for this tab."},"404":{"description":"Resource not found"},"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"},"403":{"description":"Call belongs to another agent/browser session or the inbound claim is invalid."},"404":{"description":"Resource not found"},"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"},"403":{"description":"Authenticated agent/tab does not own the call media."},"404":{"description":"Resource not found"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"q1w2e3r4t5y6u7i8o9p0="}],"ice_transport_policy":"all","expires_at":"2026-08-15T20:00:00Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 Chatwoot 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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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}/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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Feature disabled or inbox not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"]},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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"]},"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"},"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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","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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"parameters":[{"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}/health":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_id_health","summary":"Health inboxes","description":"Performs the health operation on the targeted inbox resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp Cloud phone-number health (from Meta Graph phone number node)","content":{"application/json":{"schema":{"type":"object","properties":{"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","UNKNOWN"],"example":"GREEN"},"messaging_limit_tier":{"type":"string","example":"TIER_1K"},"account_mode":{"type":"string","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"}}},"example":{"id":"123456789012345","display_phone_number":"+1 555-010-0100","verified_name":"Acme Support","name_status":"APPROVED","quality_rating":"GREEN","messaging_limit_tier":"TIER_1K","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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}}}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."}}}},"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"}}],"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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."}}}},"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"}}],"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":{"type":"object","properties":{"error":{"type":"string","example":"This inbox is in manual webhook mode. Configure the webhook in the Meta App Dashboard."}}},"example":{"error":"This inbox is in manual webhook mode. Configure the webhook in the Meta App Dashboard."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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}/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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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}/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"},"403":{"description":"Forbidden"},"404":{"description":"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 by withdrawing the calling capability from the WhatsApp provider, so the number stops placing and receiving calls. Only a WhatsApp inbox whose provider supports calling accepts this request. The response carries no body.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"WhatsApp calling disabled on the inbox. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}]}},"/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.\nONLY a WhatsApp channel accepts it: the guard asks the channel whether voice is enabled, and that question is answered by the WhatsApp channel alone — a Twilio voice inbox returns 422 here. Enabling also requires calling to be configured on the channel and the WhatsApp inbox suite to be on for the account.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Inbound-calls flag updated on the inbox. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":"Token conference","description":"Performs the token operation on the targeted conference resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Twilio Voice access token for the browser softphone","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Twilio JWT access token","example":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."},"identity":{"type":"string","example":"agent_5"},"voice_enabled":{"type":"boolean","example":true},"account_sid":{"type":"string","example":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},"agent_id":{"type":"integer","example":5},"account_id":{"type":"integer","example":1},"inbox_id":{"type":"integer","example":7},"phone_number":{"type":"string","example":"+15550100100"},"twiml_endpoint":{"type":"string","example":"https://app.example.com/twilio/voice"},"has_twiml_app":{"type":"boolean","example":true}}},"example":{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","identity":"agent_5","voice_enabled":true,"account_sid":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","agent_id":5,"account_id":1,"inbox_id":7,"phone_number":"+15550100100","twiml_endpoint":"https://app.example.com/twilio/voice","has_twiml_app":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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}/conference":{"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_conference","summary":"Delete conference","description":"Deletes the conference 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":{"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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_conference","summary":"Create conference","description":"Creates a new conference 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":{"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"call_sid":{"type":"string"},"conversation_id":{"type":"integer"}}},"example":{"call_sid":"sample call sid","conversation_id":1}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Missing template message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}}}},"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 templates","description":"Performs the sync operation on the targeted whatsapp 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":{"success":{"type":"boolean","example":true},"message_templates":{"type":"string"},"message_templates_last_updated":{"type":"string"}}},"example":{"success":true,"message_templates":"sample message templates","message_templates_last_updated":"sample message templates last updated"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Library whatsapp templates","description":"Performs the library operation on the targeted whatsapp 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":{"library":{"type":"string"}}},"example":{"library":"sample library"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 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"},"success":{"type":"boolean","example":true}}},"example":{"handle":"4:aW1hZ2U...","media_id":"123456789012345","success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Missing media or Meta rejection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"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":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates","summary":"List whatsapp templates","description":"Returns the list of whatsapp 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":"object","properties":{"approved":{"type":"string"},"last_synced":{"type":"string"},"drafts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."},"meta_template_id":{"type":"integer"},"components":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"rejection_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"example":{"payload":{"approved":"sample approved","last_synced":"sample last synced","drafts":[{"id":1,"name":"Sample Name","language":"en","category":"sample category","template_type":"standard","status":"draft","meta_template_id":1,"components":"sample components","metadata":{},"rejection_reason":"sample rejection reason","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":"Create whatsapp templates","description":"Creates a new whatsapp 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"},"language":{"type":"string"},"category":{"type":"string"},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."},"meta_template_id":{"type":"integer"},"components":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"rejection_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submit_result":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","language":"en","category":"sample category","template_type":"standard","status":"draft","meta_template_id":1,"components":"sample components","metadata":{},"rejection_reason":"sample rejection reason","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","submit_result":"sample submit result"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."}}}},"required":["whatsapp_template"]},"example":{"whatsapp_template":{"name":"Sample Name","language":"en","category":"MARKETING","template_type":"standard","status":"draft"}}}}}}},"/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 whatsapp templates","description":"Returns the whatsapp 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"},"language":{"type":"string"},"category":{"type":"string"},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."},"meta_template_id":{"type":"integer"},"components":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"rejection_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submit_result":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","language":"en","category":"sample category","template_type":"standard","status":"draft","meta_template_id":1,"components":"sample components","metadata":{},"rejection_reason":"sample rejection reason","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","submit_result":"sample submit result"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 whatsapp templates","description":"Updates the whatsapp 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"},"language":{"type":"string"},"category":{"type":"string"},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."},"meta_template_id":{"type":"integer"},"components":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"rejection_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submit_result":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","language":"en","category":"sample category","template_type":"standard","status":"draft","meta_template_id":1,"components":"sample components","metadata":{},"rejection_reason":"sample rejection reason","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","submit_result":"sample submit result"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."}}}},"required":["whatsapp_template"]},"example":{"whatsapp_template":{"name":"Sample Name","language":"en","category":"MARKETING","template_type":"standard","status":"draft"}}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Update whatsapp templates","description":"Updates the whatsapp 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"},"language":{"type":"string"},"category":{"type":"string"},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."},"meta_template_id":{"type":"integer"},"components":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Free-form metadata bag; the key set depends on the record and context."},"rejection_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submit_result":{"type":"string"}}}}},"example":{"payload":{"id":1,"name":"Sample Name","language":"en","category":"sample category","template_type":"standard","status":"draft","meta_template_id":1,"components":"sample components","metadata":{},"rejection_reason":"sample rejection reason","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","submit_result":"sample submit result"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_template":{"type":"object","properties":{"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"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"],"description":"WhatsApp template type."},"status":{"type":"string","enum":["draft","pending","approved","rejected","submission_failed"],"description":"Submission lifecycle of the WhatsApp template draft."}}}},"required":["whatsapp_template"]},"example":{"whatsapp_template":{"name":"Sample Name","language":"en","category":"MARKETING","template_type":"standard","status":"draft"}}}}}},"delete":{"tags":["Inboxes"],"operationId":"auto_delete_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_templates_id","summary":"Delete a WhatsApp message template","description":"Deletes either a local template draft by its local identifier or an approved Meta template by its Meta identifier. Approved templates are removed from Meta and immediately evicted from the inbox cache. Returns an empty 200 response when deletion succeeds.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Template deleted (empty body)."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No local draft or cached Meta template matches the identifier."},"422":{"description":"Meta rejected deletion of the approved template.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error returned while deleting the template from Meta.","example":"Meta rejected the template deletion request"}}},"example":{"error":"Meta rejected the template deletion request"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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://business.facebook.com/wa/manage/flows/123/preview/?token=abc"},"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://business.facebook.com/wa/manage/flows/123/preview/?token=abc","error":"Flow preview failed","response_body":"sample response body"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"get":{"tags":["Inboxes"],"operationId":"auto_get_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings","summary":"Get whatsapp call settings","description":"Returns the whatsapp 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":{"payload":{"type":"object","properties":{"inbox_id":{"type":"integer"},"maestro_call_agent_bot_id":{"type":"integer"},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":"integer"},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"maestro_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 whatsapp call settings","description":"Updates the whatsapp 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":{"payload":{"type":"object","properties":{"inbox_id":{"type":"integer"},"maestro_call_agent_bot_id":{"type":"integer"},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":"integer"},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"maestro_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"whatsapp_call_settings":{"type":"string"}}},"example":{"whatsapp_call_settings":"sample whatsapp call settings"}}}}},"put":{"tags":["Inboxes"],"operationId":"auto_put_api_v1_accounts_account_id_inboxes_inbox_id_whatsapp_call_settings","summary":"Update whatsapp call settings","description":"Updates the whatsapp 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":{"payload":{"type":"object","properties":{"inbox_id":{"type":"integer"},"maestro_call_agent_bot_id":{"type":"integer"},"calls_recording_enabled":{"type":"boolean"},"calls_max_seconds":{"type":"integer"},"video_calls_enabled":{"type":"boolean"},"group_calls_enabled":{"type":"boolean"}}}}},"example":{"payload":{"inbox_id":1,"maestro_call_agent_bot_id":1,"calls_recording_enabled":true,"calls_max_seconds":60,"video_calls_enabled":true,"group_calls_enabled":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"whatsapp_call_settings":{"type":"string"}}},"example":{"whatsapp_call_settings":"sample whatsapp call settings"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"CSV file is required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"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"},"403":{"description":"Forbidden"},"404":{"description":"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}}}}}}}}}},"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}]}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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":"Create orders","description":"Creates a new order from the request payload. Scoped to the account identified by `account_id` in the URL path.","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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"contact_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"external_id":{"type":"integer"},"title":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"affiliate_id":{"type":"integer"},"line_items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["order"]},"example":{"order":{"contact_id":1,"crm_item_id":1,"gateway":"asaas","external_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,"line_items":{}}}}}}}},"/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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Update orders","description":"Updates the order 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 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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"order":{"type":"object","properties":{"contact_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"external_id":{"type":"integer"},"title":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"affiliate_id":{"type":"integer"},"line_items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["order"]},"example":{"order":{"contact_id":1,"crm_item_id":1,"gateway":"asaas","external_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,"line_items":{}}}}}}},"put":{"tags":["CRM"],"operationId":"auto_put_api_v1_accounts_account_id_crm_orders_id","summary":"Update orders","description":"Updates the order 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 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","crm_item_id":1,"payments_charge_id":1,"source_connection_id":1,"owner_id":1,"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"order":{"type":"object","properties":{"contact_id":{"type":"integer"},"crm_item_id":{"type":"integer"},"gateway":{"type":"string","enum":["asaas","mercado_pago"]},"external_id":{"type":"integer"},"title":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"The recorded payment status of the order."},"ordered_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"affiliate_id":{"type":"integer"},"line_items":{"type":"object","additionalProperties":true,"description":"Free-form object."}}}},"required":["order"]},"example":{"order":{"contact_id":1,"crm_item_id":1,"gateway":"asaas","external_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,"line_items":{}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"coverage_gap":{"type":"string"},"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":"sample wired","coverage_gap":"sample coverage gap","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"coverage_gap":{"type":"string"},"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":"sample wired","coverage_gap":"sample coverage gap","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"coverage_gap":{"type":"string"},"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":"sample wired","coverage_gap":"sample coverage gap","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"coverage_gap":{"type":"string"},"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":"sample wired","coverage_gap":"sample coverage gap","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"coverage_gap":{"type":"string"},"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":"sample wired","coverage_gap":"sample coverage gap","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"string"}}},"example":{"ids":"sample ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"monitored":"sample monitored","ids":"sample ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"string"}}},"example":{"category_ids":"sample category ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"string"}}},"example":{"category_ids":"sample category ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category_ids":{"type":"string"}}},"example":{"category_ids":"sample category ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"parent_id":1,"category_ids":"sample category ids"}}}}}},"/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":"string"},"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":"sample merge","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"}}}}}},"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"}}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"string"}}},"example":{"product_ids":"sample product ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"catalog_category_id":1,"product_ids":"sample product ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"The current user may not update this product."},"404":{"description":"No such product or checklist item in this account."},"422":{"description":"Unprocessable entity"}},"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."},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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."},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."},"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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1},"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"No requested delivery could be queued, or the selection was empty or exceeded 500 unique ids."},"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]}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"type":"object","properties":{"registered":{"type":"string"},"armed":{"type":"boolean"}}},"example":{"registered":"sample registered","armed":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Missing/invalid/oversized window, empty/oversized selection, unsupported documented filter value, or a connector without documented history listing."},"409":{"description":"A different historical-sales import is already active for this account/source."},"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"type":"object","properties":{"error":{"type":"string","example":"a WhatsApp Cloud inbox_id (or waba_id + graph_token) is required"}}},"example":{"error":"a WhatsApp Cloud inbox_id (or waba_id + graph_token) is required"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"The current user may not create catalog products."},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"string"}}},"example":{"folder_ids":"sample folder ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"string"},"include_contents":{"type":"string"}}},"example":{"folder_ids":"sample folder ids","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folder_ids":{"type":"string"},"include_contents":{"type":"string"}}},"example":{"folder_ids":"sample folder ids","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"parent_id":1,"folder_ids":"sample folder ids"}}}}}},"/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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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":"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."},"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","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":5,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The asset was delivered to the conversation. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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-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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"folder_id":1,"all_matching":"sample all matching","asset_ids":"sample asset ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"all_matching":"sample all matching","asset_ids":"sample asset ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"all_matching":"sample all matching","asset_ids":"sample asset ids"}}}}}},"/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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"The asset is not archived, the preview expired, or the operation was already confirmed."},"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"}}}}},"409":{"description":"The reviewed snapshot changed, was claimed by another operation, or no longer contains this asset."}},"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"},"403":{"description":"Forbidden"},"404":{"description":"No archived media matched the reviewed selection."},"422":{"description":"The explicit selection exceeds the limit or includes media that is not archived."},"409":{"description":"The selected media belongs to more than one deletion already in progress."}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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."},"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"}}}}}},"parameters":[{"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Only administrators, or agents holding the media library management role, may start an import."},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","format":"email"},"selected_email_flags":{"type":"string","format":"email"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","format":"email"},"selected_email_flags":{"type":"string","format":"email"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"selected_email_flags":{"type":"string","format":"email"},"selected_push_flags":{"type":"string"},"notification_settings":{"type":"string"}}},"example":{"selected_email_flags":"agent@example.com","selected_push_flags":"sample selected push flags","notification_settings":"sample notification settings"}}}}},"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","format":"email"},"selected_email_flags":{"type":"string","format":"email"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"selected_email_flags":{"type":"string","format":"email"},"selected_push_flags":{"type":"string"},"notification_settings":{"type":"string"}}},"example":{"selected_email_flags":"agent@example.com","selected_push_flags":"sample selected push flags","notification_settings":"sample notification settings"}}}}}},"/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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}},"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}}}}}}},"/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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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}}}}}},"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","enabled":true,"assigned_inbox_count":5,"created_at":1,"updated_at":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":true,"voice_call_webhook_url":"https://example.com/resource","voice_status_webhook_url":"https://example.com/resource"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_limits":{"type":"string"},"account_user_ids":{"type":"string"},"routing_capacity_policy":{"type":"string"}}},"example":{"inbox_limits":"sample inbox limits","account_user_ids":"sample account user ids","routing_capacity_policy":"sample routing capacity policy"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_limits":{"type":"string"},"account_user_ids":{"type":"string"},"routing_capacity_policy":{"type":"string"}}},"example":{"inbox_limits":"sample inbox limits","account_user_ids":"sample account user ids","routing_capacity_policy":"sample routing capacity policy"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_limits":{"type":"string"},"account_user_ids":{"type":"string"},"routing_capacity_policy":{"type":"string"}}},"example":{"inbox_limits":"sample inbox limits","account_user_ids":"sample account user ids","routing_capacity_policy":"sample routing capacity policy"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"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":"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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 unified hybrid pairs","description":"Performs the deactivate unified operation on the targeted hybrid pair 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"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"Create hybrid pairs","description":"Creates a new hybrid pair 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"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"hybrid_pair":{"type":"string"}}},"example":{"hybrid_pair":"sample hybrid pair"}}}}}},"/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 hybrid pairs","description":"Returns 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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 hybrid pairs","description":"Updates the hybrid pair 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"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"hybrid_pair":"sample hybrid pair"}}}}},"put":{"tags":["WhatsApp"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hybrid_pairs_id","summary":"Update hybrid pairs","description":"Updates the hybrid pair 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"},"canonical_phone_e164":{"type":"string"},"cloud_channel_id":{"type":"integer"},"web_channel_id":{"type":"integer"},"cloud_inbox_id":{"type":["integer","null"]},"web_inbox_id":{"type":["integer","null"]},"primary":{"type":"string"},"inbound_authority":{"type":"string"},"routing":{"type":"string"},"enabled":{"type":"boolean"},"unified_inbox":{"type":"string"},"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},"audit":{"type":"string"}}},"example":{"id":1,"account_id":1,"canonical_phone_e164":"+5511999998888","cloud_channel_id":1,"web_channel_id":1,"cloud_inbox_id":1,"web_inbox_id":1,"primary":"sample primary","inbound_authority":"sample inbound authority","routing":"sample routing","enabled":true,"unified_inbox":"sample unified inbox","unified_state":{"state":"queued","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":{}},"audit":"sample audit"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"hybrid_pair":"sample hybrid pair"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Performs the sync operation on the targeted cost resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Number of cost snapshot rows upserted (or an error reason).","content":{"application/json":{"schema":{"type":"object","properties":{"synced":{"type":"integer","example":12,"description":"Snapshot rows upserted."},"error":{"type":["string","null"],"example":"not_cloud","description":"Present only on failure (e.g. not_cloud, no_business_account_id, or a Meta error message)."}}},"example":{"synced":12,"error":"not_cloud"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/whatsapp/costs":{"get":{"tags":["WhatsApp"],"operationId":"auto_get_api_v1_accounts_account_id_whatsapp_costs","summary":"List costs","description":"Returns the list of costs visible to the authenticated caller. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Aggregated Meta pricing_analytics billed cost for the window.","content":{"application/json":{"schema":{"type":"object","properties":{"display_currency":{"type":"string","example":"BRL"},"currencies":{"type":"array","items":{"type":"string"},"example":["USD"]},"by_currency":{"type":"object","additionalProperties":{"type":"number"},"description":"Raw billed cost per WABA billing currency (not converted).","example":{"USD":12.5}},"total_display":{"type":["number","null"],"example":64.75,"description":"Sum converted to display_currency; null if any currency segment lacks FX."},"total_volume":{"type":"integer","example":4820,"description":"Total billed conversations in the window."},"by_category":{"type":"object","additionalProperties":{"type":"number"},"description":"Cost per pricing_category, in display_currency.","example":{"marketing":40.0,"utility":24.75}},"by_type":{"type":"object","additionalProperties":{"type":"number"},"example":{"PMP":40.0},"description":"Cost totals (in the display currency) keyed by Meta pricing type."},"by_tier":{"type":"object","additionalProperties":{"type":"number"},"example":{"":64.75},"description":"Cost totals (in the display currency) keyed by Meta pricing tier."}}},"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}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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/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","example":"USD","description":"WABA billing currency from provider_config."},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","example":"USD"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"string"}}},"example":{"calling":"sample 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"calling":{"type":"string"}}},"example":{"calling":"sample calling"}}}}}},"/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 connections","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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"]}}}}}},"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}}}}}},"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":"Import preview connections","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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}}}},"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}}}},"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 import runs","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"},"403":{"description":"Forbidden"},"404":{"description":"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 import runs","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}}}}},"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":{}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."}}}}}}}},"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":{}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Bulk mark as paid charges","description":"Performs the bulk 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":{"succeeded_ids":{"type":"array","items":{"type":"integer"}},"failed_ids":{"type":"array","items":{"type":"integer"}}}},"example":{"succeeded_ids":[1],"failed_ids":[1]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"reason":"Sample reason.","charge_ids":"sample charge ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"reason":"Sample reason.","charge_ids":"sample charge ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"reason":"Sample reason.","charge_ids":"sample charge ids"}}}}}},"/api/v1/accounts/{account_id}/payments/charges/simulate":{"post":{"tags":["Payments"],"operationId":"auto_post_api_v1_accounts_account_id_payments_charges_simulate","summary":"Simulate charges","description":"Performs the simulate 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":{"amount":{"type":"number"},"currency":{"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."},"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."},"interest_rate":{"type":["number","null"]},"max_installments":{"type":"string"},"net_available":{"type":"string"},"net_unavailable_reason":{"type":"string"},"fee_source":{"type":"string"},"plans":{"type":"array","items":{"type":"object","properties":{"installments":{"type":"string"},"unavailable":{"type":"boolean"},"reason":{"type":"string"},"per_installment":{"type":"string"},"last_installment":{"type":"string"},"uniform":{"type":"string"},"customer_total":{"type":"number"},"merchant_net":{"type":"string"},"fee_amount":{"type":"number"},"effective_rate":{"type":"number"},"source":{"type":"string"}}}}}},"confirmation":{"type":"string"}}},"example":{"payload":{"amount":149.9,"currency":"BRL","billing_type":"pix","mode":"absorb","interest_rate":12.5,"max_installments":"sample max installments","net_available":"sample net available","net_unavailable_reason":"sample net unavailable reason","fee_source":"sample fee source","plans":[{"installments":"sample installments","unavailable":true,"reason":"Sample reason.","per_installment":"sample per installment","last_installment":"sample last installment","uniform":"sample uniform","customer_total":149.9,"merchant_net":"sample merchant net","fee_amount":149.9,"effective_rate":12.5,"source":"sample source"}]},"confirmation":"sample confirmation"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"charge":{"type":"object","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":"string"},"installment_mode":{"type":"string","enum":["absorb","passthrough"]},"installment_interest_rate":{"type":"number"}}}},"required":["charge"]},"example":{"charge":{"connection_id":1,"amount":149.9,"billing_type":"pix","installments":"sample installments","installment_mode":"absorb","installment_interest_rate":12.5}}}}}}},"/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"]},"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"]},"association_status":{"type":["string","null"],"enum":["matched","unmatched",null],"description":"Payments subscription import-time verdict on the payer (Payments::DirectoryImportService, Payments::SubscriptionAdoptionService): `matched` linked a Contact, `unmatched` left contact_id blank because no gateway customer/e-mail/phone/document exact match was found. `null` for a manually-created subscription (it always carries a contact) or a row created before this key."}}}}},"example":{"payload":{"id":1,"account_id":1,"payments_connection_id":1,"contact_id":1,"organization_id":1,"organization_name":"sample organization name","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","association_status":"matched"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"required":["subscription"]},"example":{"subscription":{"contact_id":1,"organization_id":1,"payments_plan_id":1}}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"string"}}},"example":{"subscription_ids":"sample subscription ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"string"}}},"example":{"subscription_ids":"sample subscription ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_ids":{"type":"string"}}},"example":{"subscription_ids":"sample subscription ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"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.","security":[{"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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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-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"},"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"}}}},"404":{"description":"No lifecycle event with this id in this account."},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"No lifecycle event with this id exists in this account."},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"No lifecycle event with this id exists in this account."},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"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"}}}}},"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"},"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"}}}},"404":{"description":"Resource not found"}},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"No lifecycle event with this id exists in this account."},"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"}}}}}}},"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"},"403":{"description":"The feature is disabled or the current role cannot manage commerce recovery."},"404":{"description":"No lifecycle event with this id exists in this account."},"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"}}}}}}},"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"},"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"}}}},"404":{"description":"Resource not found"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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/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, 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.","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}],"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}],"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Invalid source, contact identity, conversation, association or account scope.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"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}}}}}}},"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},"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 never change. Attribution changes require explicit audited confirmation.","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}],"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}],"fingerprint":"57bd093c095c62da2abdc0c8c81a0dfcd9f750c48f3a8f85468a24d517967e6c"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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}}},"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},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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.","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","timezone"]},"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":"Performs the bulk operation on the targeted message schedule resource. Scoped to the account identified by `account_id` in the URL path.","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"409":{"description":"A lock is stale, a schedule is executing or an action is invalid for one record."}},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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.","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"},"403":{"description":"Forbidden"},"404":{"description":"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":["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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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.","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","timezone"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"409":{"description":"Stale lock version or schedule currently executing."}},"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.","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 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"409":{"description":"Stale lock version or schedule currently executing."}},"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.","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."}}}}}}},"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":{}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}}}}},"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":{}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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","description":"IANA timezone for this scope.","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."}}}}}}},"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":{}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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","description":"IANA timezone for this scope.","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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."},"403":{"description":"Feature not enabled or insufficient access."},"404":{"description":"Resource not found"},"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."},"403":{"description":"Feature not enabled or insufficient access."},"404":{"description":"Sequence not found in this account."},"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."},"403":{"description":"Feature not enabled or insufficient access."},"404":{"description":"Sequence not found 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}/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"string"}}},"example":{"sequence_ids":"sample sequence ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"string"}}},"example":{"sequence_ids":"sample sequence ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sequence_ids":{"type":"string"}}},"example":{"sequence_ids":"sample sequence ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}},"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}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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 new sequence 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]}},"required":["name"]},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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 the sequence 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]}}},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact"}}}}},"put":{"tags":["Follow-up"],"operationId":"auto_put_api_v1_accounts_account_id_follow_up_sequences_id","summary":"Update sequences","description":"Updates the sequence 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]}}},"example":{"name":"Sample Name","description":"A short description.","status":"draft","trigger_type":"manual","trigger_event":"new_follower","target_type":"contact"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enrollment_ids":{"type":"string"},"operation":{"type":"string"}}},"example":{"enrollment_ids":"sample enrollment ids","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enrollment_ids":{"type":"string"},"operation":{"type":"string"}}},"example":{"enrollment_ids":"sample enrollment ids","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"The rendered message was created in the target conversation. No response body is returned."},"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":"forbidden"}}},"example":{"error":"forbidden"}}}},"422":{"description":"No conversation could be resolved from conversation_id, or the rendered message failed validation and was not created.","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"}}},{"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 can't be blank"},"attributes":{"type":"array","description":"Names of the message attributes that failed validation.","items":{"type":"string","description":"An invalid attribute name.","example":"content"},"example":["content"]}}}]},"example":{"error":"conversation_required"}}}}},"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":"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,"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":"sample draft"}]}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","per_page":"sample per page","has_more":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"The sequence has no published version (body `{ \"error\": \"sequence_not_published\" }`) or another machine-readable enroll reason."}},"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":"string"}}}}}}}},"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":"sample draft"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No company with this id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No template with this id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No clause with this id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Upload logo settings","description":"Performs the upload 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"setting":{"type":"string"},"logo":{"type":"string"},"logo_blob_signed_id":{"type":"integer"}}},"example":{"setting":"sample setting","logo":"sample logo","logo_blob_signed_id":1}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."}}},"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":{}},"a1_certificate":"sample a1 certificate"}}}}}},"put":{"tags":["Contracts"],"operationId":"auto_put_api_v1_accounts_account_id_contracts_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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."}}},"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":{}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded.","example":"no_destination"},"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","channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded.","example":"no_destination"},"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","channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"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"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded.","example":"no_destination"},"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","channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"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"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded.","example":"no_destination"},"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","channel":"email"}]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"No contract with this id exists in the account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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.","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"},"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"}}},"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"],"description":"A canonical token, never a sentence, so a dashboard and an agentic executor can both branch on it. Absent when the entry succeeded.","example":"no_destination"},"channel":{"type":"string","enum":["conversation","email"],"description":"Where the request went. Absent when the entry failed.","example":"email"}}}}}}}},"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,"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"},"delivery":{"status":"partial","signers":[{"signer_id":4711,"name":"Maria Souza","role":"contractor","status":"failed","reason":"no_destination","channel":"email"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No contract with this id exists in the account."},"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."},"delivery":{"$ref":"#/components/schemas/contract_delivery_report"}}}}}}},"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":{"conversation_id":{"type":"integer"}}},"example":{"conversation_id":1}}}}}},"/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"},"403":{"description":"Forbidden"},"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"}}}}}}},"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":{"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"}}}},"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"}],"meta":{"count":5,"current_page":"sample current page","total_pages":"sample total pages","has_more":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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}/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"to_owner_id":{"type":"integer"},"scope":{"type":"string"},"carried_over":{"type":"string"},"reason":{"type":"string"},"performed_by_id":{"type":"integer"},"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,"from_owner_id":1,"to_owner_id":1,"scope":"sample scope","carried_over":"sample carried over","reason":"Sample reason.","performed_by_id":1,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"to_owner_id":{"type":"integer"},"scope":{"type":"string"},"carried_over":{"type":"string"},"reason":{"type":"string"},"performed_by_id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"id":1,"account_id":1,"from_owner_id":1,"to_owner_id":1,"scope":"sample scope","carried_over":"sample carried over","reason":"Sample reason.","performed_by_id":1,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"to_owner_id":{"type":"integer"},"scope":{"type":"string"},"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"]},"record_ids":{"type":"array","items":{"type":"integer"}}}}},"required":["transfer"]},"example":{"transfer":{"from_owner_id":1,"to_owner_id":1,"scope":"sample scope","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"List leaderboard","description":"Returns the list of leaderboard 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"},"scope_type":{"type":"string","enum":["user","team"],"description":"Leaderboard slice scope — per-agent or per-team ranking."},"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"},"metric":{"type":"string"},"user_id":{"type":"integer"},"team_id":{"type":"integer"},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"rank":{"type":"string"},"value":{"type":"number"},"trend":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"account_id":1,"scope_type":"user","scope_id":1,"period_type":"week","period_start":"sample period start","metric":"sample metric","user_id":1,"team_id":1,"name":"Sample Name","avatar_url":"https://example.com/resource","rank":"sample rank","value":149.9,"trend":"sample trend","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Creates a new contest 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Updates the contest 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Updates the contest 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"},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payee_id":{"type":"integer"},"payee_type":{"type":"string","enum":["User","Sales::Affiliate"],"description":"Who the commission is owed to."},"payee_name":{"type":"string"},"currency":{"type":"string"},"period_start":{"type":"string"},"period_end":{"type":"string"},"status":{"type":"string","enum":["open","approved","paid"]},"total_accrued":{"type":"string"},"total_approved":{"type":"string"},"total_paid":{"type":"string"},"approved_by_id":{"type":"integer"},"approved_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"accruals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"source_type":{"type":"string"},"source_label":{"type":"string"},"source_id":{"type":"integer"},"gross_amount":{"type":"number"},"rate_applied":{"type":"string"},"commission_amount":{"type":"number"}}}}}},"example":{"id":1,"account_id":1,"payee_id":1,"payee_type":"User","payee_name":"sample payee name","currency":"BRL","period_start":"sample period start","period_end":"sample period end","status":"open","total_accrued":"sample total accrued","total_approved":"sample total approved","total_paid":"sample total paid","approved_by_id":1,"approved_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","accruals":[{"id":1,"source_type":"sample source type","source_label":"sample source label","source_id":1,"gross_amount":149.9,"rate_applied":"sample rate applied","commission_amount":149.9}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payee_id":{"type":"integer"},"payee_type":{"type":"string","enum":["User","Sales::Affiliate"],"description":"Who the commission is owed to."},"payee_name":{"type":"string"},"currency":{"type":"string"},"period_start":{"type":"string"},"period_end":{"type":"string"},"status":{"type":"string","enum":["open","approved","paid"]},"total_accrued":{"type":"string"},"total_approved":{"type":"string"},"total_paid":{"type":"string"},"approved_by_id":{"type":"integer"},"approved_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"accruals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"source_type":{"type":"string"},"source_label":{"type":"string"},"source_id":{"type":"integer"},"gross_amount":{"type":"number"},"rate_applied":{"type":"string"},"commission_amount":{"type":"number"}}}}}},"example":{"id":1,"account_id":1,"payee_id":1,"payee_type":"User","payee_name":"sample payee name","currency":"BRL","period_start":"sample period start","period_end":"sample period end","status":"open","total_accrued":"sample total accrued","total_approved":"sample total approved","total_paid":"sample total paid","approved_by_id":1,"approved_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","accruals":[{"id":1,"source_type":"sample source type","source_label":"sample source label","source_id":1,"gross_amount":149.9,"rate_applied":"sample rate applied","commission_amount":149.9}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"type":"object","properties":{"id":{"type":"integer","example":77},"account_id":{"type":"integer","example":1},"payee_id":{"type":"integer","example":7},"payee_name":{"type":["string","null"],"description":"The payee User's display name.","example":"Ana Vendedora"},"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":"Σ accrued commission for the period (major 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"},"accruals":{"type":"array","description":"The originating (non-reversed) accrual line-items for this payee's period, accrued_at DESC.","items":{"type":"object","properties":{"id":{"type":"integer","example":501},"source_type":{"type":"string","description":"The event class that produced the accrual. Raw Ruby class name — render source_label instead.","example":"Payments::Charge"},"source_label":{"type":"string","description":"Spec-082 — the human, TRANSLATED name of the source (account locale). Falls back to a titleized class name for a type this version does not know, never to a blank.","example":"Cobrança"},"source_id":{"type":"integer","description":"Id of the source record","so the UI can link the line back to the order/deal/charge it came from.":null,"example":8},"gross_amount":{"type":"number","description":"Order/base amount the commission was computed on (major units).","example":500.0},"rate_applied":{"type":["number","null"],"description":"Effective rate as a fraction (0.08 == 8%).","example":0.08},"commission_amount":{"type":"number","description":"Commission earned for this line (major units).","example":40.0}}}}}}},"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_name":"Ana Vendedora","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","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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"payee_id":{"type":"integer"},"payee_type":{"type":"string","enum":["User","Sales::Affiliate"],"description":"Who the commission is owed to."},"payee_name":{"type":"string"},"currency":{"type":"string"},"period_start":{"type":"string"},"period_end":{"type":"string"},"status":{"type":"string","enum":["open","approved","paid"]},"total_accrued":{"type":"string"},"total_approved":{"type":"string"},"total_paid":{"type":"string"},"approved_by_id":{"type":"integer"},"approved_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"accruals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"source_type":{"type":"string"},"source_label":{"type":"string"},"source_id":{"type":"integer"},"gross_amount":{"type":"number"},"rate_applied":{"type":"string"},"commission_amount":{"type":"number"}}}}}},"example":{"id":1,"account_id":1,"payee_id":1,"payee_type":"User","payee_name":"sample payee name","currency":"BRL","period_start":"sample period start","period_end":"sample period end","status":"open","total_accrued":"sample total accrued","total_approved":"sample total approved","total_paid":"sample total paid","approved_by_id":1,"approved_at":"2026-01-15T10:30:00.000Z","created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z","accruals":[{"id":1,"source_type":"sample source type","source_label":"sample source label","source_id":1,"gross_amount":149.9,"rate_applied":"sample rate applied","commission_amount":149.9}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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_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"},"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","error":"sample error"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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/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":{"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"},"ingest_token_configured":{"type":"boolean"},"settings":{"type":"string"}}}}},"example":{"payload":{"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","ingest_token_configured":true,"settings":"sample settings"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"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":{"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"},"ingest_token_configured":{"type":"boolean"},"settings":{"type":"string"}}}}},"example":{"payload":{"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","ingest_token_configured":true,"settings":"sample settings"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"payload":{"type":"object","properties":{"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"},"ingest_token_configured":{"type":"boolean"},"settings":{"type":"string"}}}}},"example":{"payload":{"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","ingest_token_configured":true,"settings":"sample settings"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"payload":{"type":"object","properties":{"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"},"ingest_token_configured":{"type":"boolean"},"settings":{"type":"string"}}}}},"example":{"payload":{"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","ingest_token_configured":true,"settings":"sample settings"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Get wallboard","description":"Returns the wallboard 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":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No affiliate with that id in this account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"No affiliate with that id in this account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]}}}}}}},"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"},"403":{"description":"Forbidden"},"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"}}}}}}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"]}}}}}},"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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 the new owner; the affiliate credit is untouched. 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"}}}}}},"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","example":"You are not authorized to do this action."}}}}}},"404":{"description":"No order with that id exists on the account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_found"}}}}}},"422":{"description":"Validation failed (e.g. owner_id is not a User on this account).","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Human-readable validation messages.","example":["Owner must belong to the 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","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 orders","description":"Returns the list of orders 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"},"external_id":{"type":"integer"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"]},"source":{"type":"string","enum":["manual","webhook","api","payments","commerce"]},"gateway":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"paid_at":{"type":"string","format":"date-time"},"owner_id":{"type":"integer"},"contact_id":{"type":"integer"},"contact_name":{"type":["string","null"]},"crm_item_id":{"type":"integer"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"unattributed_count":{"type":"integer"},"current_page":{"type":"string"},"total_pages":{"type":"string"},"per_page":{"type":"string"}}}}},"example":{"payload":[{"id":1,"external_id":1,"status":"pending","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":"sample current page","total_pages":"sample total pages","per_page":"sample per page"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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 reports","description":"Performs the export operation on the targeted report 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Which CSV to export. Omitted or any other value exports the commissions report.","schema":{"type":"string","enum":["commissions","leaderboard"]},"example":"leaderboard"}]}},"/api/v1/accounts/{account_id}/sales/reports":{"get":{"tags":["Sales"],"operationId":"auto_get_api_v1_accounts_account_id_sales_reports","summary":"Get reports","description":"Returns the 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":{"data":{"type":"string"}}},"example":{"data":"sample data"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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}/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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"Performs the duplicate 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":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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}/units":{"get":{"tags":["Growth Distribution"],"operationId":"auto_get_api_v1_accounts_account_id_growth_distributions_id_units","summary":"Units distributions","description":"Performs the units 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":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"distribution_id":{"type":"integer"},"sequence":{"type":"string"},"name":{"type":"string"},"jid":{"type":"string"},"whatsapp_group_id":{"type":"integer"},"invite_link":{"type":"string"},"capacity":{"type":"string"},"member_count":{"type":"integer"},"fill_rate":{"type":"number"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"next_run_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"example":{"payload":[{"id":1,"distribution_id":1,"sequence":"sample sequence","name":"Sample Name","jid":"sample jid","whatsapp_group_id":1,"invite_link":"https://example.com/resource","capacity":"sample capacity","member_count":5,"fill_rate":12.5,"status":"draft","next_run_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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Members distributions","description":"Performs the members 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":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"distribution_id":{"type":"integer"},"unit_id":{"type":"integer"},"contact_id":{"type":"integer"},"phone":{"type":"string"},"state":{"type":"string","enum":["pending","queued","invited","added","joined","failed","skipped"],"description":"Distribution member progress state."},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"source":{"type":"string"},"error_code":{"type":"string"},"added_at":{"type":"string","format":"date-time"},"joined_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,"distribution_id":1,"unit_id":1,"contact_id":1,"phone":"+5511999998888","state":"pending","join_mode":"invite_link","source":"sample source","error_code":"sample error code","added_at":"2026-01-15T10:30:00.000Z","joined_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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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":"Report distributions","description":"Performs the report 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":{"totals":{"type":"string"},"members_by_state":{"type":"object","additionalProperties":{"type":"integer"},"description":"Member counts keyed by distribution state (pending, queued, invited, added, joined, failed, skipped)."},"members_by_source":{"type":"string"},"units":{"type":"string"}}}}},"example":{"payload":{"totals":"sample totals","members_by_state":{},"members_by_source":"sample members by source","units":"sample units"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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}/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"contact_id":{"type":"integer"},"phones":{"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":"sample contact ids","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 distributions","description":"Returns the list of distributions 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"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Restrict to distributions in one state.","schema":{"type":"string","enum":["draft","active","paused","completed"]},"example":"active"}]},"post":{"tags":["Growth Distribution"],"operationId":"auto_post_api_v1_accounts_account_id_growth_distributions","summary":"Create distributions","description":"Creates a new distribution 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"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"}},"required":["name","slug"]},"example":{"name":"Sample Name","slug":"sample-slug","inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","naming_template":"sample naming template","welcome_message":"sample welcome message","community_jid":"sample community jid","channel_jid":"sample channel jid"}}}}}},"/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":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"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 distributions","description":"Updates the distribution 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"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"slug":{"type":"string"},"inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"}}},"example":{"name":"Sample Name","slug":"sample-slug","inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","naming_template":"sample naming template","welcome_message":"sample welcome message","community_jid":"sample community jid","channel_jid":"sample channel jid"}}}}},"put":{"tags":["Growth Distribution"],"operationId":"auto_put_api_v1_accounts_account_id_growth_distributions_id","summary":"Update distributions","description":"Updates the distribution 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"},"slug":{"type":"string"},"public_path":{"type":"string"},"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"settings":{"type":"string"},"units_count":{"type":"integer"},"members_count":{"type":"integer"},"open_unit_sequence":{"type":["string","null"]},"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","slug":"sample-slug","public_path":"sample public path","inbox_id":1,"logical_inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","community_jid":"sample community jid","channel_jid":"sample channel jid","naming_template":"sample naming template","welcome_message":"sample welcome message","status":"draft","settings":"sample settings","units_count":5,"members_count":5,"open_unit_sequence":"sample open unit sequence","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"slug":{"type":"string"},"inbox_id":{"type":"integer"},"launch_id":{"type":"integer"},"target_type":{"type":"string","enum":["community","group","channel"]},"join_mode":{"type":"string","enum":["invite_link","direct_add","both"]},"capacity_per_unit":{"type":"string"},"naming_template":{"type":"string"},"welcome_message":{"type":"string"},"community_jid":{"type":"string"},"channel_jid":{"type":"string"}}},"example":{"name":"Sample Name","slug":"sample-slug","inbox_id":1,"launch_id":1,"target_type":"community","join_mode":"invite_link","capacity_per_unit":"sample capacity per unit","naming_template":"sample naming template","welcome_message":"sample welcome message","community_jid":"sample community jid","channel_jid":"sample channel jid"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample settings","dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"integer"},"commenter_id":{"type":"integer"},"commenter_name":{"type":"string"},"comment_text":{"type":"string"},"comment_rule_id":{"type":"integer"},"contact_id":{"type":"integer"},"status":{"type":"string","enum":["sent","failed","skipped"],"description":"Outcome of the comment-to-DM delivery attempt."},"error_code":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{"id":1,"comment_id":1,"commenter_id":1,"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"}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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","default":1},"example":1}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample settings","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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample settings","dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"keyword":{"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"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}},"required":["dm_template"]},"example":{"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"keyword":"sample keyword","match_type":"contains","trigger_type":"keyword","platform":"any_platform","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"keywords":["sample keyword"]}}}}}},"/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":"string"},"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":"sample settings","dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample settings","dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"keyword":{"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"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"keyword":"sample keyword","match_type":"contains","trigger_type":"keyword","platform":"any_platform","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"keywords":["sample keyword"]}}}}},"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":"string"},"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":"sample settings","dm_logs_count":5,"created_at":"2026-01-15T10:30:00.000Z","updated_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"distribution_id":{"type":"integer"},"post_id":{"type":"integer"},"keyword":{"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"},"public_reply":{"type":"string"},"enabled":{"type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}}}},"example":{"name":"Sample Name","inbox_id":1,"distribution_id":1,"post_id":1,"keyword":"sample keyword","match_type":"contains","trigger_type":"keyword","platform":"any_platform","dm_template":"sample dm template","public_reply":"sample public reply","enabled":true,"keywords":["sample keyword"]}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"integer"},"caption":{"type":"string"},"thumbnail":{"type":"string"},"permalink":{"type":"string"},"timestamp":{"type":"string"}}}}}},"example":{"payload":[{"id":1,"caption":"sample caption","thumbnail":"sample thumbnail","permalink":"sample permalink","timestamp":"sample timestamp"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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/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":"integer"},"text":{"type":"string"},"username":{"type":"string"},"timestamp":{"type":"string"},"hidden":{"type":"string"},"like_count":{"type":"integer"}}}}}},"example":{"payload":[{"id":1,"text":"sample text","username":"sample username","timestamp":"sample timestamp","hidden":"sample hidden","like_count":5}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"post_id","in":"query","required":true,"description":"Post whose comments are read live from the network.","schema":{"type":"string"},"example":"17895695668004550"}]}},"/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":"Performs the hide comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"post_id":1}}}}}},"/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":"Performs the unhide comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"post_id":1}}}}}},"/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":"Performs the delete comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"post_id":1}}}}}},"/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":"Performs the reply comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"message":{"type":"string"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"message":"Sample message text.","post_id":1}}}}}},"/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":"Performs the like comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"post_id":1}}}}}},"/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":"Performs the unlike comment 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"integer"},"post_id":{"type":"integer"}}},"example":{"comment_id":1,"post_id":1}}}}}},"/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":"Performs the delete post 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":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"integer"},"comment_id":{"type":"integer"}}},"example":{"post_id":1,"comment_id":1}}}}}},"/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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"merge":{"type":"string"},"result":{"type":"object","properties":{"ok":{"type":"string"},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"error":{"type":"string"},"error_category":{"type":"string"}}}}},"example":{"merge":"sample merge","result":{"ok":"sample ok","status":"connecting","error":"sample error","error_category":"sample error category"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"merge":{"type":"string"},"result":{"type":"object","properties":{"ok":{"type":"string"},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"error":{"type":"string"},"error_category":{"type":"string"}}}}},"example":{"merge":"sample merge","result":{"ok":"sample ok","status":"connecting","error":"sample error","error_category":"sample error category"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Performs the set proxy 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":{"merge":{"type":"string"},"result":{"type":"object","properties":{"ok":{"type":"string"},"status":{"type":"string","enum":["connecting","awaiting_challenge","connected","disconnected","blocked","logged_out"],"description":"Connection state of the social account."},"error":{"type":"string"},"error_category":{"type":"string"}}}}},"example":{"merge":"sample merge","result":{"ok":"sample ok","status":"connecting","error":"sample error","error_category":"sample error category"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"proxy_url":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"verification_code":{"type":"string"}}},"example":{"proxy_url":"https://example.com/resource","username":"sample username","password":"sample-password","verification_code":"sample verification code"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"schedule_minutes":{"type":"integer"},"active":{"type":"boolean"}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true}}}}}},"/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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"schedule_minutes":{"type":"integer"},"active":{"type":"boolean"}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true}}}}},"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"schedule_minutes":{"type":"integer"},"active":{"type":"boolean"}}},"example":{"growth_social_account_id":1,"kind":"account_stats","target":"sample target","schedule_minutes":60,"active":true}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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_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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"target_id":{"type":"integer"}}},"example":{"growth_social_account_id":1,"target_id":1}}}}}},"/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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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","additionalProperties":true,"description":"Free-form object."}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}},"example":{"payload":[{}],"meta":{"count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 rules of one connected account.","schema":{"type":"integer"},"example":8},{"name":"trigger_event","in":"query","required":false,"description":"Restrict to rules fired by one trigger event.","schema":{"type":"string"},"example":"new_comment"},{"name":"platform","in":"query","required":false,"description":"Restrict to rules of one network.","schema":{"type":"string","enum":["instagram","tiktok","youtube"]},"example":"instagram"}]},"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"growth_social_account_id":{"type":"integer"},"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"}}},"example":{"name":"Sample Name","growth_social_account_id":1,"trigger_event":"new_follower","platform":"any_platform","mode":"rule","active":true}}}}}},"/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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"growth_social_account_id":{"type":"integer"},"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"}}},"example":{"name":"Sample Name","growth_social_account_id":1,"trigger_event":"new_follower","platform":"any_platform","mode":"rule","active":true}}}}},"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":{"merge":{"type":"string"}}},"example":{"merge":"sample merge"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"growth_social_account_id":{"type":"integer"},"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"}}},"example":{"name":"Sample Name","growth_social_account_id":1,"trigger_event":"new_follower","platform":"any_platform","mode":"rule","active":true}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"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":"string"},"op":{"type":"string"},"campaign_id":{"type":"integer"}}},"example":{"ids":"sample ids","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"]},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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","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"]},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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":"string"},"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":"sample attribution reason","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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":"string"},"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":"sample attribution reason","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"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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":"string"},"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":"sample attribution reason","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Test event conversion settings","description":"Performs the test event operation on the targeted conversion 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":{"results":{"type":"string"}}},"example":{"results":"sample results"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"test_event_code":{"type":"string"},"meta_waba_id":{"type":"integer"},"meta_dataset_id":{"type":"integer"},"meta_api_version":{"type":"string"},"meta_access_token":{"type":"string"}}},"example":{"use_channel_token":"sample-token","test_event_code":"sample test event code","meta_waba_id":1,"meta_dataset_id":1,"meta_api_version":"sample meta api version","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 (via Ads::Conversions::Providers::MetaCapi) for the dataset id tied to the WABA, using the saved setting optionally overridden by the channel token / meta_waba_id / meta_access_token in the body. Returns { dataset_id } on success, or { error } (no_waba / no_token / a Meta error string).","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"},"error":{"type":"string","description":"Present on failure (no_waba, no_token, or a Meta error string).","example":"no_token"}}},"example":{"dataset_id":"1234567890","error":"no_token"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","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":"Get conversion settings","description":"Returns the conversion 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":{"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"enabled":{"type":"boolean"},"meta_enabled":{"type":"boolean"},"meta_dataset_id":{"type":"integer"},"meta_waba_id":{"type":"integer"},"meta_test_event_code":{"type":"string"},"meta_partner_agent":{"type":"string"},"meta_api_version":{"type":"string"},"advanced_matching":{"type":"string"},"lead_on_capture":{"type":"string"},"contact_on_first_message":{"type":"string"},"purchase_on_won":{"type":"string"},"custom_on_lost":{"type":"string"},"purchase_on_payment":{"type":"string"},"lost_event_name":{"type":"string"},"stage_event_map":{"type":"string"},"has_meta_access_token":{"type":"boolean"},"meta_access_token_masked":{"type":"string"},"meta_ready":{"type":"boolean"},"meta_credentialed":{"type":"boolean"},"persisted":{"type":"boolean"},"suggestions":{"type":"string"}}},"example":{"inbox_id":1,"logical_inbox_id":1,"enabled":true,"meta_enabled":true,"meta_dataset_id":1,"meta_waba_id":1,"meta_test_event_code":"sample meta test event code","meta_partner_agent":"sample meta partner agent","meta_api_version":"sample meta api version","advanced_matching":"sample advanced matching","lead_on_capture":"sample lead on capture","contact_on_first_message":"sample contact on first message","purchase_on_won":"sample purchase on won","custom_on_lost":"sample custom on lost","purchase_on_payment":"sample purchase on payment","lost_event_name":"sample lost event name","stage_event_map":"sample stage event map","has_meta_access_token":true,"meta_access_token_masked":"sample meta access token masked","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":"sample suggestions"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 conversion settings","description":"Updates the conversion 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":{"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"enabled":{"type":"boolean"},"meta_enabled":{"type":"boolean"},"meta_dataset_id":{"type":"integer"},"meta_waba_id":{"type":"integer"},"meta_test_event_code":{"type":"string"},"meta_partner_agent":{"type":"string"},"meta_api_version":{"type":"string"},"advanced_matching":{"type":"string"},"lead_on_capture":{"type":"string"},"contact_on_first_message":{"type":"string"},"purchase_on_won":{"type":"string"},"custom_on_lost":{"type":"string"},"purchase_on_payment":{"type":"string"},"lost_event_name":{"type":"string"},"stage_event_map":{"type":"string"},"has_meta_access_token":{"type":"boolean"},"meta_access_token_masked":{"type":"string"},"meta_ready":{"type":"boolean"},"meta_credentialed":{"type":"boolean"},"persisted":{"type":"boolean"},"suggestions":{"type":"string"}}},"example":{"inbox_id":1,"logical_inbox_id":1,"enabled":true,"meta_enabled":true,"meta_dataset_id":1,"meta_waba_id":1,"meta_test_event_code":"sample meta test event code","meta_partner_agent":"sample meta partner agent","meta_api_version":"sample meta api version","advanced_matching":"sample advanced matching","lead_on_capture":"sample lead on capture","contact_on_first_message":"sample contact on first message","purchase_on_won":"sample purchase on won","custom_on_lost":"sample custom on lost","purchase_on_payment":"sample purchase on payment","lost_event_name":"sample lost event name","stage_event_map":"sample stage event map","has_meta_access_token":true,"meta_access_token_masked":"sample meta access token masked","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":"sample suggestions"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"enabled":{"type":"boolean"},"meta_enabled":{"type":"boolean"},"meta_dataset_id":{"type":"integer"},"meta_waba_id":{"type":"integer"},"meta_test_event_code":{"type":"string"},"meta_partner_agent":{"type":"string"},"meta_api_version":{"type":"string"},"advanced_matching":{"type":"string"},"meta_access_token":{"type":"string"},"lead_on_capture":{"type":"string"},"contact_on_first_message":{"type":"string"},"purchase_on_won":{"type":"string"},"custom_on_lost":{"type":"string"},"purchase_on_payment":{"type":"string"},"lost_event_name":{"type":"string"}}},"example":{"enabled":true,"meta_enabled":true,"meta_dataset_id":1,"meta_waba_id":1,"meta_test_event_code":"sample meta test event code","meta_partner_agent":"sample meta partner agent","meta_api_version":"sample meta api version","advanced_matching":"sample advanced matching","meta_access_token":"sample-token","lead_on_capture":"sample lead on capture","contact_on_first_message":"sample contact on first message","purchase_on_won":"sample purchase on won","custom_on_lost":"sample custom on lost","purchase_on_payment":"sample purchase on payment","lost_event_name":"sample lost event name"}}}}},"put":{"tags":["Ads"],"operationId":"auto_put_api_v1_accounts_account_id_ads_conversion_settings_inbox_id","summary":"Update conversion settings","description":"Updates the conversion 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":{"inbox_id":{"type":"integer"},"logical_inbox_id":{"type":"integer"},"enabled":{"type":"boolean"},"meta_enabled":{"type":"boolean"},"meta_dataset_id":{"type":"integer"},"meta_waba_id":{"type":"integer"},"meta_test_event_code":{"type":"string"},"meta_partner_agent":{"type":"string"},"meta_api_version":{"type":"string"},"advanced_matching":{"type":"string"},"lead_on_capture":{"type":"string"},"contact_on_first_message":{"type":"string"},"purchase_on_won":{"type":"string"},"custom_on_lost":{"type":"string"},"purchase_on_payment":{"type":"string"},"lost_event_name":{"type":"string"},"stage_event_map":{"type":"string"},"has_meta_access_token":{"type":"boolean"},"meta_access_token_masked":{"type":"string"},"meta_ready":{"type":"boolean"},"meta_credentialed":{"type":"boolean"},"persisted":{"type":"boolean"},"suggestions":{"type":"string"}}},"example":{"inbox_id":1,"logical_inbox_id":1,"enabled":true,"meta_enabled":true,"meta_dataset_id":1,"meta_waba_id":1,"meta_test_event_code":"sample meta test event code","meta_partner_agent":"sample meta partner agent","meta_api_version":"sample meta api version","advanced_matching":"sample advanced matching","lead_on_capture":"sample lead on capture","contact_on_first_message":"sample contact on first message","purchase_on_won":"sample purchase on won","custom_on_lost":"sample custom on lost","purchase_on_payment":"sample purchase on payment","lost_event_name":"sample lost event name","stage_event_map":"sample stage event map","has_meta_access_token":true,"meta_access_token_masked":"sample meta access token masked","meta_ready":true,"meta_credentialed":true,"persisted":true,"suggestions":"sample suggestions"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"enabled":{"type":"boolean"},"meta_enabled":{"type":"boolean"},"meta_dataset_id":{"type":"integer"},"meta_waba_id":{"type":"integer"},"meta_test_event_code":{"type":"string"},"meta_partner_agent":{"type":"string"},"meta_api_version":{"type":"string"},"advanced_matching":{"type":"string"},"meta_access_token":{"type":"string"},"lead_on_capture":{"type":"string"},"contact_on_first_message":{"type":"string"},"purchase_on_won":{"type":"string"},"custom_on_lost":{"type":"string"},"purchase_on_payment":{"type":"string"},"lost_event_name":{"type":"string"}}},"example":{"enabled":true,"meta_enabled":true,"meta_dataset_id":1,"meta_waba_id":1,"meta_test_event_code":"sample meta test event code","meta_partner_agent":"sample meta partner agent","meta_api_version":"sample meta api version","advanced_matching":"sample advanced matching","meta_access_token":"sample-token","lead_on_capture":"sample lead on capture","contact_on_first_message":"sample contact on first message","purchase_on_won":"sample purchase on won","custom_on_lost":"sample custom on lost","purchase_on_payment":"sample purchase on payment","lost_event_name":"sample lost event name"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"No such ad account in this account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"EAAG..."}}},"example":{"inbox_id":137,"access_token":"EAAG..."}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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":"sample 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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"No such campaign in this account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"No such campaign in this account."},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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 conversation context","description":"Returns the conversation context 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":{"ad_referral":{"type":"string"},"window":{"type":"string"}}},"lead":{"type":"string"},"campaign":{"type":"string"}}},"example":{"payload":{"ad_referral":"sample ad referral","window":"sample window"},"lead":"sample lead","campaign":"sample campaign"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"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"},"403":{"description":"Forbidden"},"404":{"description":"No internal chat channel with this id is visible to the caller."},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"user_id":{"type":"integer"}}},"example":{"user_ids":"sample user ids","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"201":{"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}]}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Not authorized to share this entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"not_authorized"}}}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"entity_not_found"}}}}}},"422":{"description":"Unsupported entity type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"unsupported_entity"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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/{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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"greeting":{"type":"string"}}},"example":{"greeting":"sample greeting"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"greeting":{"type":"string"}}},"example":{"greeting":"sample greeting"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"group_jid":{"type":"string"},"join_action":{"type":"string"},"link_code":{"type":"string"}}},"example":{"requests":"sample requests","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":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"name":"Sample Name","description":"A short description.","groups":"sample groups"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Create sync","description":"Creates a new sync from the request payload. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"202":{"description":"Full WhatsApp Hub synchronization was queued for the selected Web transport.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","inbox_id"],"properties":{"status":{"type":"string","enum":["enqueued"],"description":"Stable acknowledgement that the asynchronous job was queued.","example":"enqueued"},"inbox_id":{"type":"integer","description":"Immutable physical WhatsApp Web inbox whose data will be synchronized.","example":6},"logical_inbox_id":{"type":"integer","description":"Agent-facing unified inbox identity. Omitted when it is identical to inbox_id.","example":15}}},"example":{"status":"enqueued","inbox_id":6,"logical_inbox_id":15}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"ai":{"type":"string"},"greeting":{"type":"string"}}}}},"example":{"payload":{"inbox_id":1,"logical_inbox_id":1,"engagement":"sample engagement","sync":"sample sync","broadcast":"sample broadcast","ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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 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":{"inbox_id":{"type":["integer","null"]},"logical_inbox_id":{"type":"integer"},"engagement":{"type":"string"},"sync":{"type":"string"},"broadcast":{"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","ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"engagement":{"type":"string"},"ai":{"type":"string"}}},"example":{"engagement":"sample engagement","ai":"sample ai"}}}}},"put":{"tags":["WhatsApp Hub"],"operationId":"auto_put_api_v1_accounts_account_id_whatsapp_hub_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":{"inbox_id":{"type":["integer","null"]},"logical_inbox_id":{"type":"integer"},"engagement":{"type":"string"},"sync":{"type":"string"},"broadcast":{"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","ai":"sample ai","greeting":"sample greeting"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"engagement":{"type":"string"},"ai":{"type":"string"}}},"example":{"engagement":"sample engagement","ai":"sample ai"}}}}}},"/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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"session_id":{"type":"integer"},"status":{"type":"string","enum":["draft","published","retired"]},"version_id":{"type":"integer"},"messages_skipped":{"type":"boolean"}}}}},"example":{"payload":{"session_id":1,"status":"draft","version_id":1,"messages_skipped":true}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}},"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}}}}},"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"]}}}}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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."}}}},"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":{}}],"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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","example":"trigger_conversation_created","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"]},"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":"Test http request flows","description":"Performs the test http request 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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."},"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","body_mode":"fields","body_content_type":"json","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"]}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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."}}}},"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":{}}],"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"},"403":{"description":"Forbidden"},"404":{"description":"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."}}}},"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":{}}],"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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."}}}}}},"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"]}}}}}}}}},"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"]}}}}}}}}}},"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."}}}},"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":{}}],"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."}}}},"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":{}}],"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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."}}}}}},"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"]}}}}}}}}},"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"]}}}}}}}}}},"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."}}}},"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":{}}],"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_commerce","trigger_crm_item","trigger_calendar_booking",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"},"403":{"description":"Forbidden"},"404":{"description":"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"template_key":{"type":"string"},"inbox_ids":{"type":"string"},"flow":{"type":"string"}}},"example":{"template_key":"sample-token","inbox_ids":"sample inbox ids","flow":"sample flow"}}}}}},"/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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"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 flows","description":"Updates the 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"},"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_ids":{"type":"string"},"flow":{"type":"string"}}},"example":{"inbox_ids":"sample inbox ids","flow":"sample flow"}}}}},"put":{"tags":["Flow Builder"],"operationId":"auto_put_api_v1_accounts_account_id_flow_builder_flows_id","summary":"Update flows","description":"Updates the 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"},"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_commerce","trigger_crm_item","trigger_calendar_booking"]},"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_conversation_created","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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_ids":{"type":"string"},"flow":{"type":"string"}}},"example":{"inbox_ids":"sample inbox ids","flow":"sample flow"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample variables","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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":"string"},"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":"sample variables","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"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":"sample variables","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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.","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"},"403":{"description":"Forbidden"},"404":{"description":"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 without payloads.","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"string"},"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":"sample variables","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"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":"sample variables","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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 that support Liquid rendering.","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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"}}}},"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"}],"meta":{"current_page":"sample current page","total_count":5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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.","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},"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}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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 authorizations","description":"Performs the connect 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":{"type":"object","properties":{"success":{"type":"string"},"channel_id":{"type":"integer"}}},"example":{"success":"sample success","channel_id":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Disconnect authorizations","description":"Performs the disconnect 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":{"type":"object","properties":{"success":{"type":"boolean","example":true}}},"example":{"success":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Logout authorizations","description":"Performs the logout 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":{"type":"object","properties":{"success":{"type":"string"},"code":{"type":"string"}}},"example":{"success":"sample success","code":"sample code"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Reauthorize authorizations","description":"Performs the reauthorize 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":{"type":"object","properties":{"success":{"type":"string"},"channel_id":{"type":"integer"},"force_logout":{"type":"string"}}},"example":{"success":"sample success","channel_id":1,"force_logout":"sample force logout"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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 qr authorizations","description":"Performs the retry qr 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":{"type":"object","properties":{"success":{"type":"boolean","example":true},"channel_id":{"type":"integer"}}},"example":{"success":true,"channel_id":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"type":"object","properties":{"success":{"type":"string"},"channel_id":{"type":"integer"},"applied":{"type":"string"}}},"example":{"success":"sample success","channel_id":1,"applied":"sample applied"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"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)."},"inbox_id":{"type":"integer"}}},"example":{"provider_user_id":1,"features":{},"inbox_id":1}}}}}},"/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 Chatwoot 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":{"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},"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},"route_released":true,"reconnect_scheduled":true}}}}}},"401":{"description":"The caller is not an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"The account feature required by the requested route mode is disabled.","content":{"application/json":{"schema":{"type":"object","required":["error","error_code"],"properties":{"error":{"type":"string","example":"This route option is not enabled for the account."},"error_code":{"type":"string","enum":["feature_not_enabled"],"example":"feature_not_enabled"}}},"example":{"error":"This route option is not enabled for the account.","error_code":"feature_not_enabled"}}}},"404":{"description":"No WhatsApp Web inbox with this identifier belongs to the current account. The response has no body."},"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"}}}},"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"}}}},"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"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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. When the managed-proxy feature is enabled, `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 Chatwoot 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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"The caller is not an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}},"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":{"status":{"type":"string","enum":["active"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy"],"example":"managed_proxy"},"route_version":{"type":"integer","minimum":1,"example":1},"fallback_policy":{"type":"string","enum":["hold","managed_proxy"],"example":"hold"},"fail_closed":{"type":"boolean","example":true},"provider":{"type":"string","enum":["webshare","bright_data","custom"],"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":{"status":{"type":"string","enum":["active"],"example":"active"},"route_type":{"type":"string","enum":["managed_proxy","mobile_egress"],"example":"mobile_egress"},"route_version":{"type":"integer","minimum":1,"example":1},"fallback_policy":{"type":"string","enum":["hold","managed_proxy"],"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},"session_pending":true,"session_pending_code":"timeout_budget_exhausted"}}}},"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"}}}},"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"}}}}},"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"},"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},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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"},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"401":{"description":"The caller is not an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}},"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"}}}}},"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"}}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"422":{"description":"Unprocessable entity"},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"404":{"description":"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/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 an account administrator, or its access role is missing inbox and WhatsApp-hub management. A failed authorization check answers 401 on this API, never 403.","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"}}}},"403":{"description":"Forbidden"},"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"}}}},"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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"participant_action":{"type":"string"},"phones":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"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"},"403":{"description":"Forbidden"},"404":{"description":"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_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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"participants":{"type":"string"},"participant_action":{"type":"string"},"phones":{"type":"string"},"jid":{"type":"string"}}},"example":{"name":"Sample Name","participants":"sample participants","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 (Chatwoot 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 Chatwoot 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"},"403":{"description":"Forbidden"},"404":{"description":"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_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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"group":"sample group","join_action":"sample join action","requests":"sample requests"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"name":"Sample Name","description":"A short description.","groups":"sample groups"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"message_ids":"sample message ids"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"}}},"example":{"newsletters":"sample newsletters"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":{"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"},"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"}}}},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"string"},"exclude_list":{"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.","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},"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 Chatwoot 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}}},"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","example":true},"logged_in":{"type":"boolean","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"},"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,"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},"ban":{"banned":false,"ttl_seconds":3600},"gateway":{"reachable":true,"connected":true,"logged_in":true,"jid":"5521999999999:1@s.whatsapp.net","push_name":"Support","webhook":"https://app.example.com/webhooks/whatsapp_web/9d19f6","status_code":200}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"string"}}},"example":{"entries":"sample entries"}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"No requested delivery could be queued, or the selection was empty or exceeded 500 unique ids."},"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]}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"type":"object","properties":{"message":{"type":["string","null"]}}},"example":{"message":"Sample message text."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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}}}}}}},"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":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}},"example":{"id":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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":"Auth shopify","description":"Performs the auth operation on the targeted shopify 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":{"redirect_url":{"type":"string"}}},"example":{"redirect_url":"https://example.com/resource"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_domain":{"type":"string"}}},"example":{"shop_domain":"sample shop domain"}}}}}},"/api/v1/accounts/{account_id}/integrations/shopify/orders":{"get":{"tags":["Integrations"],"operationId":"auto_get_api_v1_accounts_account_id_integrations_shopify_orders","summary":"Orders shopify","description":"Performs the orders operation on the targeted shopify 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":{"orders":{"type":"array","items":{"type":"string"}}}},"example":{"orders":["sample order"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/accounts/{account_id}/integrations/shopify":{"delete":{"tags":["Integrations"],"operationId":"auto_delete_api_v1_accounts_account_id_integrations_shopify","summary":"Delete shopify","description":"Deletes the shopify 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Linear API error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Linear API error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","example":{"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Bug report settings linear","description":"Performs the bug report settings operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Bug-report Linear team/label configuration","content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean","example":true},"team_id":{"type":["string","null"],"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"label_ids":{"type":"array","items":{"type":"string"},"example":["l1b2c3d4-e5f6","l9a8b7c6-d5e4"]},"reply_marker":{"type":["string","null"],"description":"Marker THIS account configured, verbatim, or null when it is inheriting. Never resolved here: null means \"inherit\", and an operator reading a resolved value in this field could not tell an explicit choice from an inherited one.","example":"[cliente]"},"effective_reply_marker":{"type":"string","description":"The marker a maintainer must actually type TODAY, after account -\u003e installation -\u003e default resolution. An empty string means replies to the reporter are disabled entirely; it never means \"publish everything\".","example":"[cliente]"}}},"example":{"connected":true,"team_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","label_ids":["l1b2c3d4-e5f6","l9a8b7c6-d5e4"],"reply_marker":"[cliente]","effective_reply_marker":"[cliente]"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"tags":["Integrations"],"operationId":"auto_put_api_v1_accounts_account_id_integrations_linear_bug_report_settings","summary":"Update bug report settings linear","description":"Performs the update bug report settings operation on the targeted linear resource. Scoped to the account identified by `account_id` in the URL path.","security":[{"userApiKey":[]}],"responses":{"200":{"description":"Updated bug-report Linear configuration","content":{"application/json":{"schema":{"type":"object","properties":{"connected":{"type":"boolean","example":true},"team_id":{"type":["string","null"],"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"label_ids":{"type":"array","items":{"type":"string"},"example":["l1b2c3d4-e5f6"]},"reply_marker":{"type":["string","null"],"description":"Marker THIS account configured, verbatim, or null when it is inheriting. Never resolved here: null means \"inherit\", and an operator reading a resolved value in this field could not tell an explicit choice from an inherited one.","example":"[cliente]"},"effective_reply_marker":{"type":"string","description":"The marker a maintainer must actually type TODAY, after account -\u003e installation -\u003e default resolution. An empty string means replies to the reporter are disabled entirely; it never means \"publish everything\".","example":"[cliente]"}}},"example":{"connected":true,"team_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","label_ids":["l1b2c3d4-e5f6"],"reply_marker":"[cliente]","effective_reply_marker":"[cliente]"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Linear not connected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Linear is not connected"}}}}}}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Bug-report routing for this account's own Linear. `reply_marker` is stored RAW: send an empty value to inherit the installation default, or one of `off` / `none` / `disabled` to stop publishing Linear comments to the reporter. It is deliberately NOT a closed set — an operator may choose any prefix — so it carries no enum.","content":{"application/json":{"schema":{"type":"object","properties":{"team_id":{"type":["string","null"],"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"label_ids":{"type":"array","items":{"type":"string"},"example":["l1b2c3d4-e5f6"]},"reply_marker":{"type":["string","null"],"example":"[cliente]"}}},"example":{"team_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","label_ids":["l1b2c3d4-e5f6"],"reply_marker":"[cliente]"}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Unauthorized"},"403":{"description":"Forbidden"},"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."},"422":{"description":"Unprocessable entity"}},"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.","additionalProperties":{"type":"integer","description":"New zero-based position of the category identified by the key."}}},"required":["positions_hash"]},"example":{"positions_hash":{"41":0,"42":1,"43":2}}}}}}},"/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"},"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,"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"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}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}},"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"}}}}}},"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"}}}}}},"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"}}}}}}}}},"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Unauthorized"},"403":{"description":"Forbidden"},"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."},"422":{"description":"Unprocessable entity"}},"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.","additionalProperties":{"type":"integer","description":"New zero-based position of the article identified by the key."}}},"required":["positions_hash"]},"example":{"positions_hash":{"901":0,"902":1}}}}}}},"/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"]},"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."},"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."},"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":"string"}}}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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."},"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","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","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","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":"sample draft"}],"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"]},"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."},"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."},"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":"string"}}}},"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","format":"email"},"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"]},"agent_bot_working_hours_mode":{"type":"string","enum":["always","inside_business_hours","outside_business_hours"]},"business_name":{"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"},"content_templates":{"type":"string"},"auth_token":{"type":"string"},"account_sid":{"type":"string"},"api_key_sid":{"type":"string"},"email":{"type":"string","format":"email"},"auth_method":{"type":"string"},"forwarding_enabled":{"type":"boolean"},"forward_to_email":{"type":"string","format":"email"},"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":"string"},"provider_config":{"type":"string"},"hybrid_pair":{"type":"string"},"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"},"voice_enabled":{"type":"boolean"},"inbound_calls_enabled":{"type":"boolean"},"voice_configured":{"type":"boolean"},"has_api_key_secret":{"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."},"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","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","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","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":"sample draft"}],"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","agent_bot_working_hours_mode":"always","business_name":"sample business name","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","content_templates":"sample content templates","auth_token":"sample-token","account_sid":"sample account sid","api_key_sid":"sample api key sid","email":"agent@example.com","auth_method":"sample auth method","forwarding_enabled":true,"forward_to_email":"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":"sample message templates","provider_config":"sample provider config","hybrid_pair":"sample hybrid pair","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","voice_enabled":true,"inbound_calls_enabled":true,"voice_configured":true,"has_api_key_secret":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","thumbnail":"sample thumbnail","custom_role_id":1,"access_role_id":1}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"meta":{"type":"array","items":{"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","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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"]},"meta":{"type":"array","items":{"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","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"},"403":{"description":"Forbidden"},"404":{"description":"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":"Create upload","description":"Creates a new upload 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"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"attachment":{"type":"string"},"external_url":{"type":"string"}}},"example":{"attachment":"sample attachment","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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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..."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"Jhj5dZrVaK7ZwHHjRyZWjbDl"},"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":"Jhj5dZrVaK7ZwHHjRyZWjbDl","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":[{"userApiKey":[]}],"responses":{"401":{"description":"Unauthorized"},"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"}}}}}},"404":{"description":"Account not found for the given email/account."},"422":{"description":"Unprocessable entity"},"307":{"description":"Temporary redirect to the SAML initiation URL (/auth/saml?account_id=...\u0026RelayState=...)."}},"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":{"type":"object","properties":{"access_token":{"type":"string"},"account_id":{"type":["integer","null"]},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"email":{"type":"string","format":"email"},"hmac_identifier":{"type":"string"},"id":{"type":"integer"},"inviter_id":{"type":["integer","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"pubsub_token":{"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, ...)."},"role":{"type":["string","null"],"enum":["agent","administrator",null]},"ui_settings":{"type":"string"},"uid":{"type":"string"},"type":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"onboarding_step":{"type":"string"},"active_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["agent","administrator"]},"permissions":{"type":"string"},"access_role_id":{"type":["integer","null"]},"access_role":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"type":"string"}}}}}}}},"example":{"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","id":1,"inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","custom_attributes":{},"role":"agent","ui_settings":"sample ui settings","uid":"sample uid","type":"sample type","accounts":[{"id":1,"name":"Sample Name","status":"active","onboarding_step":"sample onboarding step","active_at":"2026-01-15T10:30:00.000Z","role":"agent","permissions":"sample permissions","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":"sample field permissions"}}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}},"/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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"The signed-in user is not a member of the account in the payload."},"422":{"description":"Unprocessable entity"},"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":1,"custom_role":{}}]}}}}},"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"}}}}}}},"/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":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"The signed-in user is not a member of the account in the payload."},"422":{"description":"Unprocessable entity"},"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":1,"custom_role":{}}]}}}}},"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}}}}}}},"/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."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"string"}}},"example":{"profile":"sample profile"}}}}}},"/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."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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":{"type":"object","properties":{"access_token":{"type":"string"},"account_id":{"type":["integer","null"]},"available_name":{"type":"string"},"avatar_url":{"type":"string"},"confirmed":{"type":"boolean"},"display_name":{"type":"string"},"message_signature":{"type":"string"},"email":{"type":"string","format":"email"},"hmac_identifier":{"type":"string"},"id":{"type":"integer"},"inviter_id":{"type":["integer","null"]},"name":{"type":"string"},"provider":{"type":"string","enum":["email","google_oauth2","saml"],"description":"Authentication provider the user signed up through."},"pubsub_token":{"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, ...)."},"role":{"type":["string","null"],"enum":["agent","administrator",null]},"ui_settings":{"type":"string"},"uid":{"type":"string"},"type":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"onboarding_step":{"type":"string"},"active_at":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["agent","administrator"]},"permissions":{"type":"string"},"access_role_id":{"type":["integer","null"]},"access_role":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"field_permissions":{"type":"string"}}}}}}}},"example":{"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","id":1,"inviter_id":1,"name":"Sample Name","provider":"email","pubsub_token":"sample-token","custom_attributes":{},"role":"agent","ui_settings":"sample ui settings","uid":"sample uid","type":"sample type","accounts":[{"id":1,"name":"Sample Name","status":"active","onboarding_step":"sample onboarding step","active_at":"2026-01-15T10:30:00.000Z","role":"agent","permissions":"sample permissions","access_role_id":1,"access_role":{"id":1,"name":"Sample Name","field_permissions":"sample field permissions"}}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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"}}},"example":{"feature_available":true,"enabled":true,"backup_codes_generated":true}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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":"string"}}}},"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":"sample current"}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/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)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{}}}}}}}},"/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":[{"userApiKey":[]}],"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."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}},"/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":[{"userApiKey":[]}],"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":"string"},"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":"sample disable branding","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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/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":[{"userApiKey":[]}],"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"}]}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/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":[{"userApiKey":[]}],"responses":{"204":{"description":"Event dispatched. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{}}}}}}},"/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":[{"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"},"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}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_messages","summary":"Create messages","description":"Creates a new message from the request payload.","security":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"message":{"type":"array","items":{"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"]}}}}}},"/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":[{"userApiKey":[]}],"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":{}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}}},"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":[{}]}}}}},"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":[{"userApiKey":[]}],"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":{}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}}},"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":[{}]}}}}}},"/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":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_attribute":{"type":"string"},"inbox_id":{"type":"integer"}}},"example":{"custom_attribute":"sample custom attribute","inbox_id":1}}}}}},"/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":[{"userApiKey":[]}],"responses":{"204":{"description":"Custom attributes replaced. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"The visitor has no conversation open in this inbox."},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"message":{"type":"array","items":{"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":{}}}}}}},"/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":[{"userApiKey":[]}],"responses":{"200":{"description":"Last-seen stamped and read receipts scheduled. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/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":[{"userApiKey":[]}],"responses":{"200":{"description":"Typing status broadcast. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"The visitor has no conversation open in this inbox."},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"message":{"type":"array","items":{"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":{}}}}}}},"/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":[{"userApiKey":[]}],"responses":{"200":{"description":"Transcript accepted for delivery, provided an e-mail address is known for the visitor. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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."}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/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":[{"userApiKey":[]}],"responses":{"200":{"description":"Conversation resolved, or already resolved. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"This inbox does not allow visitors to end conversations."},"404":{"description":"The visitor has no conversation open in this inbox."}}}},"/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":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]},"post":{"tags":["Widget"],"operationId":"auto_post_api_v1_widget_conversations","summary":"Create conversations","description":"Creates a new conversation from the request payload.","security":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"array","items":{"type":"object","additionalProperties":true,"description":"Free-form object."}},"message":{"type":"array","items":{"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":{}}}}}}},"/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":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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/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":[{"userApiKey":[]}],"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"}}}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}}},"/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":[{"userApiKey":[]}],"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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":[{"userApiKey":[]}],"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"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":[{"userApiKey":[]}],"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}}},"/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":[{"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"},"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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number for pagination."}]}},"/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":[{"userApiKey":[]}],"responses":{"204":{"description":"Request accepted; the label was added when it exists in the account. Empty body."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}}},"/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":[{"userApiKey":[]}],"responses":{"204":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/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":[{"userApiKey":[]}],"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":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}},"example":{"id":"7f9a1b2c-3d4e-5f60-7182-9a0b1c2d3e4f","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"inbox_id":{"type":"integer"}}},"example":{"inbox_id":1}}}}}},"/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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/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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"},"403":{"description":"Forbidden"},"404":{"description":"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"}}}}}}},"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":"access-token-abc123"},"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":"access-token-abc123","accounts":[{"id":1,"name":"Acme Support","active_at":"2026-01-15T10:30:00.000Z","role":"administrator","locale":"en"}]}}}}},"401":{"description":"Unauthorized"},"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"}}}}}},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"S3cureP@ss!"},"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":"S3cureP@ss!","locale":"en","domain":"acme.com","support_email":"help@acme.com","user_full_name":"Alex Owner","h_captcha_client_response":"10000000-aaaa-bbbb-cccc-000000000001"}}}}}},"/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}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}},"404":{"description":"Resource not found"},"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)"}}}}}}},"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":"ya29.sample-access-token","refresh_token":"1//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":{"401":{"description":"Missing or invalid Platform App access token."},"403":{"description":"Forbidden"},"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"}}}},"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":["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)"},"401":{"description":"Missing or invalid Platform App access token."},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}}}},"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. The transport is stateless: each POST is self-contained and must send `Accept: application/json`. 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)"},"401":{"description":"Missing or invalid Platform App access token (a user token is rejected here). The `WWW-Authenticate` header advertises the Protected Resource Metadata."},"403":{"description":"Forbidden"},"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"}}}},"422":{"description":"Unprocessable entity"},"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":{"type":"object","additionalProperties":true,"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},"error":null}}}},"202":{"description":"Notification accepted (a JSON-RPC message without an `id`). No response body."},"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"}}}}},"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":{}}}}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}}}}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"boolean"},"joined_at":{"type":"string","format":"date-time"}}}}}},"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":true,"joined_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"boolean"},"joined_at":{"type":"string","format":"date-time"}}}}}},"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":true,"joined_at":"2026-01-15T10:30:00.000Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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":"boolean"},"joined_at":{"type":"string","format":"date-time"}}},"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":true,"joined_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":"boolean"},"joined_at":{"type":"string","format":"date-time"}}},"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":true,"joined_at":"2026-01-15T10:30:00.000Z"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":[{}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{"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"}}},"example":{"status":"unavailable","reason":"pending_app_review"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}}}},"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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}}}},"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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"No signer matches this signing token."},"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"}}}}}},"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}}}}}},"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"}}}}}}},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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":"Get wallboard","description":"Returns the wallboard identified by the path parameters.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"string"}}},"example":{"payload":"sample payload"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"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}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"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"}}}}}}},"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":"Create ingest","description":"Creates a new ingest from the request payload.","security":[],"responses":{"200":{"description":"Redelivery of an order already ingested. 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 order had already been ingested.","example":"duplicate"}}},"example":{"status":"duplicate"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}},"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"gateway":{"type":"string"},"external_id":{"type":"integer"},"title":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","paid","partially_paid","overdue","refunded","canceled","failed"],"description":"Order status recorded in the registry (log only; never charges)."},"crm_item_id":{"type":"integer"},"ordered_at":{"type":"string","format":"date-time"},"paid_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."},"raw":{"type":"string"},"affiliate_id":{"type":"integer"},"line_items":{"type":"string"},"name":{"type":"string"}}},"example":{"contact_id":1,"email":"agent@example.com","phone_number":"+5511999998888","gateway":"sample gateway","external_id":1,"title":"Sample title","amount":149.9,"currency":"BRL","status":"pending","crm_item_id":1,"ordered_at":"2026-01-15T10:30:00.000Z","paid_at":"2026-01-15T10:30:00.000Z","metadata":{},"raw":"sample raw","affiliate_id":1,"line_items":"sample line items","name":"Sample Name"}}}}}},"/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"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"},"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"}}}}}},"/webhooks/twitter":{"get":{"tags":["Inbound Webhooks"],"operationId":"auto_get_webhooks_twitter","summary":"Twitter crc webhooks","description":"Performs the twitter crc operation on the targeted webhook resource.","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"response_token":{"type":"string"}}},"example":{"response_token":"sample-token"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"crc_token","in":"query","required":true,"description":"Challenge token sent by the platform; the response echoes its HMAC-SHA256 signature.","schema":{"type":"string"},"example":"abc123"}]},"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_twitter","summary":"Twitter/X account activity webhook","description":"Receives the Twitter Account Activity envelope (DMs, tweets). The GET counterpart answers the CRC challenge.","security":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"for_user_id":{"type":"string","example":"2244994945"},"direct_message_events":{"type":"array","description":"Twitter/X direct-message events from the Account Activity webhook.","items":{"type":"object","additionalProperties":true,"description":"One direct-message event object."}}}},"example":{"for_user_id":"2244994945","direct_message_events":[{}]}}}}}},"/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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":[{}]}}}}}},"/webhooks/telegram/{bot_token}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_telegram_bot_token","summary":"Telegram bot webhook","description":"Receives the Telegram Bot API Update object for the bot identified by the path token.","security":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"bot_token","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":{}}}}}}},"/webhooks/sms/{phone_number}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_sms_phone_number","summary":"SMS (Bandwidth) webhook","description":"Receives the Bandwidth messaging callback — a JSON ARRAY of message events for the number in the path.","security":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":"string","example":"message-received"},"message":{"type":"object","additionalProperties":true,"description":"Inbound SMS provider message payload."}}}},"example":[{"type":"message-received","message":{}}]}}}}},"/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"}}}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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"}}]}},"/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"}}}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}},"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string"}}]},"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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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":{}}]}]}}}}}},"/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."},"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."},"400":{"description":"The request body is not valid JSON."},"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":{}}}}}}},"/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."},"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."},"400":{"description":"The request body is not valid JSON."},"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"}}]}},"/webhooks/bug_reports/linear":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_bug_reports_linear","summary":"Process install linear","description":"Performs the process install operation on the targeted linear resource.","security":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}}}},"/webhooks/bug_reports/linear/{account_id}":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_bug_reports_linear_account_id","summary":"Receive a Linear issue event","description":"Status sync-back from the account's own Linear workspace for the bug reports raised from this installation. The delivery is authenticated by recomputing the HMAC-SHA256 of the raw body with the per-account secret stored when the webhook was registered, comparing it in constant time with the Linear-Signature header and requiring the webhookTimestamp to be recent; only then is the issue update applied to the matching bug report. The response is an empty acknowledgement with no body.","security":[],"responses":{"200":{"description":"Event processed. Empty body."},"401":{"description":"Signature missing or invalid, timestamp outside the freshness window, or no Linear webhook secret is stored for the account in the path."},"500":{"description":"Unexpected failure while processing the event; Linear should retry."}},"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Linear-Signature","in":"header","required":true,"description":"`HMAC_SHA256(\u003cper-account webhook secret\u003e, \u003craw request body\u003e)`, hex-encoded (no prefix). The secret is the one stored on the account's Linear integration when the webhook was registered. Compared in constant time; a missing or mismatching value is rejected with 401.","schema":{"type":"string"}}]}},"/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. 421/422 signals Meta to refresh keys.","security":[],"responses":{"200":{"description":"Base64 encrypted response payload.","content":{"text/plain":{"schema":{"type":"string","example":"kJ8s0d...base64..."}}}},"401":{"description":"Invalid signature."},"403":{"description":"Forbidden"},"404":{"description":"Unknown flow endpoint identifier."},"422":{"description":"Missing private key / decryption failure (Meta re-syncs keys)."}},"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 401 on mismatch whenever an app secret is configured; when none is, the check is skipped and the RSA key exchange is the only gate. 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"}}}}}},"/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":[],"responses":{"200":{"description":"Event applied, or acknowledged and ignored because it repeats a delivery already seen or refers to an unknown call. Empty body."},"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."},"400":{"description":"The request body is not valid JSON."},"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"}}]}},"/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":[],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged as a repeated delivery. Empty body."},"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."},"400":{"description":"The request body is not valid JSON."},"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"}}]}},"/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":[],"responses":{"200":{"description":"Event accepted for ingestion, or acknowledged as a repeated delivery. Empty body."},"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."},"400":{"description":"The request body is not valid JSON."},"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"}}]}},"/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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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}}}}}}},"/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":[],"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"}}}},"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."},"422":{"description":"Unprocessable entity"},"200":{"description":"Published flow — session started (or a replay was acked without starting a second session)."},"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 9f2c1d7a4b6e8130a5c2f7e0d4b9a1c8"}},{"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"}}}}}},"/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":[],"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":{}}}}}},"/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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":{}}}}}}},"/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":[],"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."},"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."},"400":{"description":"The X-Goog-Channel-ID header is missing."},"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"}}]}},"/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"}}}}}},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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":[],"responses":{"200":{"description":"Acknowledged (the literal JSON string \"ok\").","content":{"application/json":{"schema":{"type":"string","example":"ok"},"example":"ok"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"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":[{}]}}}},"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."},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}},"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":[],"responses":{"200":{"description":"Success (no content)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"422":{"description":"Unprocessable entity"}},"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":[{}]}}}}}},"/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":[],"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"}}]}},"/webhooks/shopify":{"post":{"tags":["Inbound Webhooks"],"operationId":"auto_post_webhooks_shopify","summary":"Receive a Shopify 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. Only the shop redaction topic acts on the payload, removing the stored Shopify integration hooks of that shop domain; every other topic is accepted and ignored. The response is an empty acknowledgement with no body.","security":[],"responses":{"200":{"description":"Delivery verified; acted upon when it is a shop redaction, ignored otherwise. 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":false,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_domain":{"type":"string"}}},"example":{"shop_domain":"sample shop domain"}}}},"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":false,"description":"The Shopify webhook topic being delivered. Only `shop/redact` acts on the payload; every other topic is verified and acknowledged without further work.","schema":{"type":"string","example":"shop/redact"}}]}},"/.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","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 Model Context Protocol revision the servers implement.","example":"2025-11-25"},"x_chatwoot_mcp":{"type":"object","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"}}}}},"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":"2025-11-25","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"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"}}}}},"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"}}},"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":"Automation Rule event, on which we call the actions(conversation_created, conversation_updated, message_created)","enum":["conversation_created","conversation_updated","message_created"],"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"}}},"actions":{"type":"array","description":"Array of actions which we perform when condition matches","items":{"type":"object","properties":{"action_name":{"type":"string"},"action_params":{"type":"array","items":{"type":"string"}}},"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","properties":{"id":{"type":"integer","description":"ID of the logo file"},"portal_id":{"type":"integer","description":"ID of the portal this logo belongs to"},"file_type":{"type":"string","description":"MIME type of the file","enum":["image","audio","video","file"]},"account_id":{"type":"integer","description":"ID of the account"},"file_url":{"type":"string","description":"URL to access the logo file"},"blob_id":{"type":"integer","description":"ID of the blob"},"filename":{"type":"string","description":"Name of the file"}}},"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"},"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"]},"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"},"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"},"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":{"id":{"type":"number","description":"The ID of the message"},"content":{"type":"string","description":"The text content of the message"},"account_id":{"type":"number","description":"The ID of the account"},"inbox_id":{"type":"number","description":"The ID of the inbox"},"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."},"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","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"]},"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":true,"description":"Custom role assigned to the user in this account (id, name and permissions), or null when the user has a built-in role."}}}}}},"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"},"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 Web delivery controls such as pacing, batching, variant randomization and spintax.","example":{}},"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"}}},"inbox":{"type":"object","properties":{"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"},"business_name":{"type":["string","null"],"description":"Business name associated with the inbox"},"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"},"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."}}},"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 configuration of the bot (e.g. the pre-chat form fields collected before handing over to the bot)."},"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_paid","payment_charge_overdue","payment_charge_refunded","payment_charge_failed","payment_charge_canceled","payment_subscription_created","payment_subscription_renewed","payment_subscription_canceled","payment_subscription_payment_failed","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_failed","distribution_unit_created","distribution_unit_full","distribution_completed","social_comment_captured","ads_lead_captured","sales_goal_reached","sales_tier_reached","sales_team_reward_granted","sales_commission_accrued","sales_portfolio_transferred","sales_badge_awarded","sales_owner_changed","order_registered","order_status_changed","order_paid","order_refunded","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"],"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.","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}}},"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 user who performed the action"},"user_type":{"type":["string","null"],"enum":["User",null],"description":"The type of user who performed the action; null for system-initiated changes."},"username":{"type":"string","description":"The email/username of the user who performed the action"},"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_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."},"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"}}},"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":"Map of account feature flags to toggle (true enables, false/blank disables). The properties below enumerate the COMPLETE feature registry of this installation; each flag's default is the state a new account starts with. Omitted keys keep their current value.","additionalProperties":false,"example":{"inbound_emails":true,"help_center":true,"campaigns":false},"properties":{"account_brain":{"type":"boolean","description":"Enables the Account Brain feature.","default":false},"ads_conversion_tracking":{"type":"boolean","description":"Enables the Ad Conversion Tracking (Meta CAPI) feature.","default":false},"ads_manager":{"type":"boolean","description":"Enables the Ads Manager feature.","default":false},"advanced_assignment":{"type":"boolean","description":"Enables the Advanced Assignment feature.","default":false},"advanced_search":{"type":"boolean","description":"Enables the Advanced Search feature.","default":false},"advanced_search_indexing":{"type":"boolean","description":"Enables the Advanced Search Indexing feature.","default":false},"affiliate_program":{"type":"boolean","description":"Enables the Affiliate Program feature.","default":false},"agent_bots":{"type":"boolean","description":"Enables the Agent Bots feature.","default":true},"agent_management":{"type":"boolean","description":"Enables the Agent Management feature.","default":true},"ai_onboarding":{"type":"boolean","description":"Enables the AI Onboarding (Generative Setup) feature.","default":false},"assignment_v2":{"type":"boolean","description":"Enables the Assignment V2 feature.","default":true},"audit_logs":{"type":"boolean","description":"Enables the Audit Logs feature.","default":false},"auto_resolve_conversations":{"type":"boolean","description":"Enables the Auto Resolve Conversations feature.","default":true},"automations":{"type":"boolean","description":"Enables the Automations feature.","default":true},"bug_reports":{"type":"boolean","description":"Enables the Bug Reports feature.","default":true},"calendar":{"type":"boolean","description":"Enables the Calendar feature.","default":false},"campaigns":{"type":"boolean","description":"Enables the Campaigns feature.","default":true},"canned_responses":{"type":"boolean","description":"Enables the Canned Responses feature.","default":true},"captain_document_auto_sync":{"type":"boolean","description":"Enables the Captain Document Auto Sync feature.","default":false},"captain_integration":{"type":"boolean","description":"Enables the Captain feature.","default":false},"captain_integration_v2":{"type":"boolean","description":"Enables the Captain V2 feature.","default":false},"captain_tasks":{"type":"boolean","description":"Enables the Captain Tasks feature.","default":false},"captain_v1_action_classifier":{"type":"boolean","description":"Enables the Captain V1 Action Classifier feature.","default":false},"catalog":{"type":"boolean","description":"Enables the Product Catalog feature.","default":true},"channel_email":{"type":"boolean","description":"Enables the Email Channel feature.","default":true},"channel_facebook":{"type":"boolean","description":"Enables the Facebook Channel feature.","default":true},"channel_instagram":{"type":"boolean","description":"Enables the Instagram Channel feature.","default":true},"channel_tiktok":{"type":"boolean","description":"Enables the TikTok Channel feature.","default":true},"channel_voice":{"type":"boolean","description":"Enables the Voice Channel feature.","default":false},"channel_website":{"type":"boolean","description":"Enables the Website Channel feature.","default":true},"chatwoot_v4":{"type":"boolean","description":"Enables the Chatwoot V4 feature.","default":true},"commerce_recovery":{"type":"boolean","description":"Enables the Commerce Recovery (Sales Recovery) feature.","default":false},"companies":{"type":"boolean","description":"Enables the Companies feature.","default":false},"contact_chatwoot_support_team":{"type":"boolean","description":"Enables the Contact Chatwoot Support Team feature.","default":true},"contracts":{"type":"boolean","description":"Enables the Contracts \u0026 E-signature feature.","default":false},"conversation_glance_signals":{"type":"boolean","description":"Enables the Conversation Glance Signals feature.","default":false},"conversation_required_attributes":{"type":"boolean","description":"Enables the Required Conversation Attributes feature.","default":false},"conversation_unread_counts":{"type":"boolean","description":"Enables the Conversation Unread Counts feature.","default":true},"crm":{"type":"boolean","description":"Enables the CRM feature.","default":true},"crm_integration":{"type":"boolean","description":"Enables the CRM Integration feature.","default":false},"crm_pipelines":{"type":"boolean","description":"Enables the CRM Pipelines feature.","default":true},"crm_v2":{"type":"boolean","description":"Enables the CRM V2 feature.","default":false},"csat_review_notes":{"type":"boolean","description":"Enables the CSAT Review Notes feature.","default":false},"custom_attributes":{"type":"boolean","description":"Enables the Custom Attributes feature.","default":true},"custom_reply_domain":{"type":"boolean","description":"Enables the Custom Reply Domain feature.","default":false},"custom_reply_email":{"type":"boolean","description":"Enables the Custom Reply Email feature.","default":false},"custom_roles":{"type":"boolean","description":"Enables the Custom Roles feature.","default":false},"custom_tools":{"type":"boolean","description":"Enables the Custom Tools feature.","default":false},"dashboard_apps_native_surfaces":{"type":"boolean","description":"Enables the Dashboard Apps Native Surfaces feature.","default":false},"disable_branding":{"type":"boolean","description":"Enables the Disable Branding feature. Deprecated flag, kept for backwards compatibility.","default":false},"email_continuity_on_api_channel":{"type":"boolean","description":"Enables the Email Continuity on API Channel feature.","default":false},"engagement_tracking":{"type":"boolean","description":"Enables the Engagement \u0026 Lead Score feature.","default":false},"field_level_permissions":{"type":"boolean","description":"Enables the Field-level Permissions feature.","default":true},"flow_builder":{"type":"boolean","description":"Enables the Flow Builder feature.","default":false},"flow_builder_runtime_v2":{"type":"boolean","description":"Enables the Flow Builder Runtime V2 feature.","default":false},"follow_ups":{"type":"boolean","description":"Enables the Follow-up feature.","default":false},"governance_lgpd":{"type":"boolean","description":"Enables the Governance \u0026 LGPD feature.","default":false},"granular_permissions":{"type":"boolean","description":"Enables the Granular Permissions feature.","default":true},"growth_ads":{"type":"boolean","description":"Enables the Growth Ads (CTWA \u0026 Lead Ads) feature.","default":false},"growth_social":{"type":"boolean","description":"Enables the Growth Social (Comment-to-DM) feature.","default":false},"growth_social_automation":{"type":"boolean","description":"Enables the Growth Social Automation (IG/TikTok/YouTube) feature.","default":false},"guided_tours":{"type":"boolean","description":"Enables the Guided Tours feature.","default":false},"help_center":{"type":"boolean","description":"Enables the Help Center feature.","default":true},"help_center_embedding_search":{"type":"boolean","description":"Enables the Help Center Embedding Search feature.","default":false},"inbound_emails":{"type":"boolean","description":"Enables the Inbound Emails feature.","default":true},"inbox_management":{"type":"boolean","description":"Enables the Inbox Management feature.","default":true},"inbox_view":{"type":"boolean","description":"Enables the Inbox View feature.","default":false},"insert_article_in_reply":{"type":"boolean","description":"Enables the Insert Article in Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"integrations":{"type":"boolean","description":"Enables the Integrations feature.","default":true},"internal_chat":{"type":"boolean","description":"Enables the Internal Chat feature.","default":false},"ip_lookup":{"type":"boolean","description":"Enables the IP Lookup feature.","default":false},"labels":{"type":"boolean","description":"Enables the Labels feature.","default":true},"launch_group_distribution":{"type":"boolean","description":"Enables the Launch Group Distribution feature.","default":false},"linear_integration":{"type":"boolean","description":"Enables the Linear Integration feature.","default":false},"macros":{"type":"boolean","description":"Enables the Macros feature.","default":true},"maestro_byok":{"type":"boolean","description":"Enables the Maestro BYOK (Account LLM Keys) feature.","default":true},"maestro_global_keys":{"type":"boolean","description":"Enables the Maestro Installation LLM Keys (Global Fallback) feature.","default":false},"mcp":{"type":"boolean","description":"Enables the MCP (Model Context Protocol) feature.","default":false},"media_library":{"type":"boolean","description":"Enables the Media Library feature.","default":true},"message_reply_to":{"type":"boolean","description":"Enables the Message Reply To feature. Deprecated flag, kept for backwards compatibility.","default":false},"message_scheduling":{"type":"boolean","description":"Enables the Message Scheduling feature.","default":false},"native_advanced_search":{"type":"boolean","description":"Enables the Advanced Search (Native) feature.","default":false},"native_audit_trail":{"type":"boolean","description":"Enables the Audit Trail (Native) feature.","default":false},"native_event_pipeline_v2":{"type":"boolean","description":"Enables the Native Event Pipeline V2 feature.","default":false},"notion_integration":{"type":"boolean","description":"Enables the Notion Integration feature.","default":false},"orders_registry":{"type":"boolean","description":"Enables the CRM Orders Registry feature.","default":false},"organizations":{"type":"boolean","description":"Enables the Organizations (Companies \u0026 Relationships) feature.","default":false},"outbound_agent_name_header":{"type":"boolean","description":"Enables the Outbound Agent Name Header feature.","default":false},"payments":{"type":"boolean","description":"Enables the Payments feature.","default":false},"platform_governance":{"type":"boolean","description":"Enables the Platform Governance feature.","default":true},"quoted_email_reply":{"type":"boolean","description":"Enables the Quoted Email Reply feature. Deprecated flag, kept for backwards compatibility.","default":false},"realtime_translation":{"type":"boolean","description":"Enables the Realtime Translation feature.","default":false},"reply_mailer_migration":{"type":"boolean","description":"Enables the Reply Mailer Migration feature.","default":false},"report_rollup":{"type":"boolean","description":"Enables the Report Rollup feature.","default":false},"reports":{"type":"boolean","description":"Enables the Reports feature.","default":true},"sales_management":{"type":"boolean","description":"Enables the Sales Management feature.","default":false},"saml":{"type":"boolean","description":"Enables the SAML feature.","default":false},"search_with_gin":{"type":"boolean","description":"Enables the Search messages with GIN feature.","default":false},"session_analytics":{"type":"boolean","description":"Enables the Session Analytics feature.","default":false},"setup_blueprints":{"type":"boolean","description":"Enables the Setup Blueprints feature.","default":false},"shopify_integration":{"type":"boolean","description":"Enables the Shopify Integration feature.","default":false},"sla":{"type":"boolean","description":"Enables the SLA feature.","default":false},"smart_routing":{"type":"boolean","description":"Enables the Smart Routing feature.","default":false},"social_collaboration":{"type":"boolean","description":"Enables the Social Collaboration Network (Matrix) feature.","default":false},"tasks":{"type":"boolean","description":"Enables the Tasks feature.","default":false},"team_management":{"type":"boolean","description":"Enables the Team Management feature.","default":true},"unified_revenue_ledger":{"type":"boolean","description":"Enables the Unified Revenue Ledger feature.","default":false},"usage_metering":{"type":"boolean","description":"Enables the Usage Metering feature.","default":false},"voice_recorder":{"type":"boolean","description":"Enables the Voice Recorder feature.","default":true},"whatsapp_campaign":{"type":"boolean","description":"Enables the WhatsApp Campaign feature.","default":false},"whatsapp_embedded_signup":{"type":"boolean","description":"Enables the WhatsApp Embedded Signup feature. Deprecated flag, kept for backwards compatibility.","default":false},"whatsapp_hub":{"type":"boolean","description":"Enables the WhatsApp Hub feature.","default":false},"whatsapp_hybrid_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Inbox feature.","default":false},"whatsapp_hybrid_unified_inbox":{"type":"boolean","description":"Enables the WhatsApp Hybrid Unified Inbox feature.","default":false},"whatsapp_inbox_suite":{"type":"boolean","description":"Enables the WhatsApp Inbox Suite feature.","default":false},"whatsapp_mobile_egress":{"type":"boolean","description":"Enables the WhatsApp Web Mobile Connection feature.","default":false},"whatsapp_web_proxy":{"type":"boolean","description":"Enables the WhatsApp Web Global Proxy feature.","default":false},"white_label":{"type":"boolean","description":"Enables the White Label feature.","default":false},"workforce_management":{"type":"boolean","description":"Enables the Team Management feature.","default":false}}},"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"}}}},"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"}}},"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"}}},"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":"ya29.sample-access-token","refresh_token":"1//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 configuration for the bot (e.g. the pre-chat form fields collected before handing over to the bot).","example":{}}}},"user_create_update_payload":{"type":"object","properties":{"name":{"type":"string","description":"Name of the user","example":"Daniel"},"display_name":{"type":"string","description":"Display name of the user","example":"Dan"},"email":{"type":"string","description":"Email of the user","example":"daniel@acme.inc"},"password":{"type":"string","description":"Password must contain uppercase, lowercase letters, number and a special character","example":"Password2!"},"custom_attributes":{"type":"object","description":"Custom attributes you want to associate with the user","example":{},"additionalProperties":true}}},"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"},"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":{"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","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"},"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"},"business_name":{"type":"string","description":"Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n","example":"My Business"},"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"}]}}},"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"}},"example":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id"}}}},{"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"],"properties":{"type":{"type":"string","enum":["sms"],"example":"sms"},"phone_number":{"type":"string","description":"SMS phone number","example":"+15551234567"},"provider_config":{"type":"object","additionalProperties":true,"description":"Provider-specific SMS configuration (Bandwidth credentials such as account_id, application_id, api_key and api_secret)","example":{"account_id":"your-account-id","application_id":"your-application-id"}}}},"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"}},"example":{"api_key":"your-api-key","phone_number_id":"your-phone-number-id","business_account_id":"your-business-account-id"}}}},"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":true,"description":"Provider-specific SMS configuration (Bandwidth credentials such as account_id, application_id, api_key and api_secret)","example":{"api_key":"your-api-key","api_secret":"your-api-secret","application_id":"your-application-id","account_id":"your-account-id"}}}},"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"}}},"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 (editable after close)"},"close_reason":{"type":"string","description":"The close reason (mainly for lost deals)"},"pipeline_id":{"type":"number","description":"The pipeline to place the deal in"},"stage_id":{"type":"number","description":"The stage to place the deal in"},"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."},"stats":{"type":"object","additionalProperties":false,"description":"Allowlisted counters for the most recent run.","properties":{"total":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"meta_validated":{"type":"integer","minimum":0},"dry_run":{"type":"boolean"}}},"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},"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},"dry_run":{"type":"boolean"},"truncated":{"type":"boolean"},"failed_ids":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string","maxLength":200},"reason":{"type":["string","null"],"maxLength":120}}}},"skipped_ids":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string","maxLength":200},"reason":{"type":["string","null"],"maxLength":120}}}}}},"error":{"type":["string","null"],"description":"Sanitized run diagnostic; authentication material is removed."},"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_paid","payment_charge_overdue","payment_charge_refunded","payment_charge_failed","payment_charge_canceled","payment_subscription_created","payment_subscription_renewed","payment_subscription_canceled","payment_subscription_payment_failed","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_failed","distribution_unit_created","distribution_unit_full","distribution_completed","social_comment_captured","ads_lead_captured","sales_goal_reached","sales_tier_reached","sales_team_reward_granted","sales_commission_accrued","sales_portfolio_transferred","sales_badge_awarded","sales_owner_changed","order_registered","order_status_changed","order_paid","order_refunded","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","enum":["conversation_created","conversation_updated","conversation_resolved","message_created"],"example":"message_created","description":"The event when you want to execute the automation actions"},"active":{"type":"boolean","description":"Enable/disable automation rule"},"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","properties":{"color":{"type":"string","description":"Header color for help-center in hex format","example":"#FFFFFF"},"custom_domain":{"type":"string","description":"Custom domain to display help center.","example":"help.example.com"},"header_text":{"type":"string","description":"Help center header","example":"Handbook"},"homepage_link":{"type":"string","description":"link to main dashboard","example":"https://www.example.com/"},"name":{"type":"string","description":"Name for the portal","example":"Handbook"},"page_title":{"type":"string","description":"Page title for the portal","example":"Handbook"},"slug":{"type":"string","description":"Slug for the portal to display in link","example":"handbook"},"archived":{"type":"boolean","description":"Status to check if portal is live","example":false},"config":{"type":"object","additionalProperties":true,"description":"Configuration about supporting locales (allowed_locales array and default_locale)","example":{"allowed_locales":["en","es"],"default_locale":"en"}}}},"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"}}},"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"}}},"payment_charge":{"type":"object","description":"A charge (cobrança) with the normalized status, buyer-facing payment artifacts (PIX copia-e-cola, QR, hosted/boleto links) and catalog/deal line items. No gateway secrets.","properties":{"id":{"type":"number"},"account_id":{"type":"number"},"payments_connection_id":{"type":["number","null"],"description":"Native gateway connection when this installation owns one; null for an external sale."},"contact_id":{"type":"number"},"conversation_id":{"type":"number"},"crm_item_id":{"type":"number"},"payments_subscription_id":{"type":"number"},"gateway_charge_id":{"type":"string"},"external_reference":{"type":"string"},"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"]},"amount":{"type":"number"},"amount_refunded":{"type":"number"},"currency":{"type":"string"},"installments":{"type":"number"},"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","description":"PIX copia-e-cola."},"pix_qr_base64":{"type":"string"},"boleto_url":{"type":"string"},"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, hence not enumerated here), 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, `imported` when pulled by a backfill. Such a charge is treated as HISTORY: it is recorded in full (charge, events, order, reports) but produces no customer message, no ad-platform conversion, no commission, no lead score and no outbound account webhook. Absent on a charge created through this API."}}},"gateway_options":{"type":"object","additionalProperties":true,"description":"Sanitized gateway-native options applied at creation; never contains credentials."},"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"},"contact_name":{"type":"string"},"gateway":{"type":"string","description":"Immutable source namespace stored on the charge (for example asaas, mercado_pago, hotmart or kiwify).","example":"hotmart"},"archived_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"catalog_variant_id":{"type":"number"},"catalog_product_id":{"type":"number"},"name_snapshot":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"},"line_total":{"type":"number"},"currency":{"type":"string"},"position":{"type":"number"}}}}}},"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"},"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":"Immutable purchase-history record in the CRM Orders Registry. 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","contact_name","crm_item_id","payments_charge_id","source_connection_id","owner_id","voided_at","voided_by_id","void_reason","void_kind","gateway","external_id","title","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"]},"crm_item_id":{"type":["integer","null"],"minimum":1},"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},"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},"currency":{"type":["string","null"],"example":"BRL"},"status":{"type":"string","enum":["pending","paid","partially_paid","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 financial facts.","required":["source","target_contact","records","changes","conflicts","blocked","historical","commission_impact","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","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":["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}}}},"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","crm_order","commerce_event"],"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"],"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"],"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}}}},"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_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 Chatwoot; `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 Chatwoot (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},"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":"An attendee's RSVP state for a calendar event."},"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). An absent key uses the shipped copy.","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":{"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 pay_first slot stash 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":{"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 Chatwoot `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","format":"float","description":"Cost in USD, as measured at call time (never re-priced later).","example":0.0375},"unpriced_calls":{"type":"integer","description":"Calls in this bucket whose `cost_usd` is NOT a measurement — no rate table exists for the surface, or the model that served the turn has no published price. Above zero means this row's cost is a floor, not a total.","example":2}}},"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_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":"Generative voice - the agent answers with a native voice note (PTT).","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"},"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"],"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","description":"READ-ONLY. Names of the secrets currently configured, without their values.","items":{"type":"string","example":"ACME_API_TOKEN"}},"provider_keys":{"type":["object","null"],"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"],"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","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","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 Chatwoot account that owns this Robô.","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 Chatwoot account that owns this Modelo.","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":{"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."}}}},"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}},"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."},"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."},"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://app.conversalabs.com.br/oauth/mcp/authorize","tokenUrl":"https://app.conversalabs.com.br/oauth/mcp/token","refreshUrl":"https://app.conversalabs.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":"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":"Assignable Agents","description":"Assignable Agents endpoints"},{"name":"Assignment Policies","description":"Assignment Policies endpoints"},{"name":"Auth","description":"Auth endpoints"},{"name":"Authentication","description":"Authentication 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":"Callbacks","description":"Callbacks 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":"Contact Inboxes","description":"Contact Inboxes endpoints"},{"name":"Contracts","description":"Contracts 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":"Engagement","description":"Engagement 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":"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":"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":"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":"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"}],"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":["Access Roles","Ads","Agent Bots","Agent Capacity Policies","Assignable Agents","Assignment Policies","Auth","Authentication","Bug Reports","Bulk Actions","CRM","CRM Item Line Items","CSAT Survey Responses","Callbacks","Campaigns","Captain","Catalog","Channels","Commerce","Companies","Contact Inboxes","Contracts","Custom Roles","Custom Scripts","Dashboard App SDK","Dashboard Apps","Engagement","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","Monitoring","Notification Subscriptions","Notifications","Notion","Oauth-protected-resource","Onboarding","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","Routing Policies","SAML","SLA Policies","Sales","Search","Setup","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"]}]}