Set up ConversationArc with confidence.

ConversationArc REST API and MCP

The REST API and remote MCP server operate on the same durable records as the browser UI. Personal keys are tenant-scoped and role-scoped; changing a tenant ID cannot expand access.

Base URL: https://correspond.outliyr.com

Authentication

Create a personal agent key in Team. Choose read-only or read/write access and an expiration of 7, 30, 90, or 365 days. The key is shown once and stored by ConversationArc only as a hash. Rotation immediately invalidates the previous key.

export CORRESPOND_MCP_TOKEN='paste-the-one-time-key-here'
curl --fail-with-body \
  --header "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  https://correspond.outliyr.com/api/workflows

Do not commit or send the key. The platform-operator token is not a customer credential and is intentionally undocumented.

Authorization rules

• Read-only keys can call REST GET routes and non-mutating MCP tools.
• Write keys remain bounded by the member role.
• Workflow writes require owner, administrator, or editor; destructive workflow operations require owner or administrator.
• Team invitation/revocation and tenant export require owner.
• Redacted support bundles allow owner, administrator, or support.
• Cross-tenant access returns 404 not_found for tenant-scoped personal keys.
• Routes or tools labeled platform operator cannot be called with a customer key.

Common errors are 400 invalid_request for request/schema validation, 401 unauthorized, 403 forbidden, 403 agent_key_scope_forbidden, 404 not_found, 409 state conflict, and 429 rate limited. 422 is reserved for the narrower resource-template or style-policy validation contracts; it is not the generic schema-validation response.

REST examples

List and inspect workflows:

curl --fail-with-body \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  https://correspond.outliyr.com/api/workflows

curl --fail-with-body \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  https://correspond.outliyr.com/api/workflows/WORKSPACE/WORKFLOW

Pause several workflows atomically. Every selected workflow must belong to the key's tenant and be eligible; otherwise none are changed.

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  https://correspond.outliyr.com/api/workflows/WORKSPACE/bulk-pause \
  -d '{"workflow_ids":["active-a","active-b"],"confirm_workflow_ids":["active-a","active-b"]}'

Archive a workflow non-destructively:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  https://correspond.outliyr.com/api/workflows/WORKSPACE/welcome/archive \
  -d '{"confirm_workflow_id":"welcome"}'

Download a redacted support bundle:

curl --fail-with-body \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  'https://correspond.outliyr.com/api/tenants/WORKSPACE/support-bundle?limit=25'

REST route inventory

Parameters beginning with : are path parameters. Request and response schemas are enforced by the current server. Read the record before a mutation and preserve unknown fields; do not infer writable fields from response fields.

Team, settings, audit, diagnostics, usage, and billing

Funnel and activity

Native Instagram inbox

These routes operate only on user-initiated Instagram conversations already admitted to the workspace. Every reply rechecks the connected account, permission, and reply window; an ineligible thread makes no provider call and returns the native Instagram handoff.

Platform declarations and adapters

Instagram OAuth handoff for agents

An owner or administrator using a write-scoped personal agent key may start the

same Instagram OAuth authorization handoff through

POST /api/meta/:tenant/connections/instagram/oauth/start or the

start_instagram_oauth_connection MCP tool. The response contains an

authorization URL. Treat that URL as a secret: it is single-use and expires in

10 minutes. Deliver it only to the owner or administrator who will complete the

provider flow; do not log it, add it to source control, or send it through an

untrusted channel.

This starts no connection by itself. It is not a Turnstile or login bypass, it

does not issue browser cookies or expose an Instagram password or access token,

and it still requires the intended account holder to consent at Meta. The

connection record and encrypted provider credential are created only after the

provider callback succeeds. Instagram disconnect remains a normal

owner/administrator connection operation.

Outbound webhooks

Send a signed HTTP POST to your own systems when something happens in a

conversation. This is the generic integration seam: it works with Zapier, Make,

n8n, a CRM, or your own backend without ConversationArc shipping a per-vendor

adapter.

Every request carries x-conversationarc-signature: t=<unix-seconds>,v1=<hex>.

The signed material is "<t>.<raw-body>", HMAC-SHA256 with the endpoint's

signing secret. Verify the signature AND reject a timestamp outside your

tolerance window, or a captured request can be replayed against you. The secret

is returned exactly once, at creation, and cannot be read back afterwards.

Current event types: conversation.replied, conversation.delivery_failed,

destination.clicked, subscriber.captured, review.created,

review.expiring, and review.resolved. Natural Intent review events contain

the review ID, deep link, and deadline—not a person's comment, identity, or

reply text. Their binding behavior is defined in

docs/superpowers/specs/2026-08-06-natural-intent-routing.md.

Owners can export one participant's eligible profile and conversation journey

with GET /api/tenants/:tenant/participants/:participant/export or the

export_participant_data MCP tool. The export is tenant-scoped, audited,

bounded to 200 interactions, and excludes provider credentials, internal

tenant identifiers, and secret hashes.

Failed deliveries are retried with exponential backoff and remain visible with

their error code. An endpoint that keeps failing is marked dead rather than

retried forever; nothing is silently dropped.

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $CORRESPOND_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  https://correspond.outliyr.com/api/webhooks/WORKSPACE/endpoints \
  -d '{"url":"https://hooks.example.com/in","description":"CRM","event_types":["conversation.replied"]}'

Calendly booking attribution

Know which conversation produced a booking, not just who clicked the link. No

OAuth and no Calendly API access: paste the signing key Calendly shows when you

create a webhook subscription, and point that subscription at

https://app.conversationarc.com/webhooks/calendly/WORKSPACE.

When someone books through a ConversationArc tracked link, the click token

rides as utm_content, Calendly returns it on invitee.created, and the

booking is recorded against that conversation as a custom_conversion funnel

event. Outbound destination.booked and destination.booking_canceled webhook

events fire at the same time. Invitee names, emails, and question answers are

never stored.

SMS consent evidence

These endpoints manage consent evidence. Carrier setup and sending use the

Twilio connection routes above. Phone numbers are normalized for the request

and stored only as tenant-scoped recipient hashes; raw web IP addresses are

hashed before persistence.

Resources and content sources

Workflows and versions

Personalization review and experiments

Natural Intent routing and review

Natural Intent is available alongside literal keyword triggers. The browser,

REST API, and MCP operate on the same workflow mode, durable decision record,

editable review, notification preferences, and audit evidence. The canonical

behavior is docs/superpowers/specs/2026-08-06-natural-intent-routing.md.

Authenticated tenant-scoped operations let a workspace:

• configure keyword or natural_intent on a workflow draft and choose

Catch every opportunity, Balanced, or Only obvious requests;

• preview or shadow-evaluate a comment against an exact workflow version with

zero provider calls;

• list and inspect decisions with intent, confidence, explanation, risk,

selected approved resource, timing, policy version, and provider deadline;

• resolve a review with Send as written, Edit and send, Choose another approved resource, or Do nothing using one atomic confirmation-bound mutation;
• record a creator correction without silently changing the active policy;
• configure in-app/email, optional Slack, and signed webhook alerts; and
• read notification delivery health and the audit trail.

GET /api/personalization/:tenant/reviews provides the review read model and

POST /api/personalization/:tenant/reviews/:review/:decision records the

review decision. Existing approve/reject compatibility remains supported. All

schemas are enforced server-side; use the browser or the MCP tools in the

inventory below rather than guessing request bodies.

MCP configuration

Use the Streamable HTTP endpoint at /mcp:

{
  "mcpServers": {
    "conversationarc": {
      "type": "http",
      "url": "https://correspond.outliyr.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CORRESPOND_MCP_TOKEN}"
      }
    }
  }
}

The checked-in examples/claude-code.mcp.json is equivalent. POST /mcp is the protocol transport. Direct browser GET /mcp and DELETE /mcp are not customer tool calls.

Personal keys automatically supply actor, tenant, role, and scopes. A tool's optional tenant_id cannot escape that tenant. Mutations write the same audit log as browser and REST changes.

Customer MCP tool inventory

Read and reporting:

get_tenant_settings, get_tenant_usage, get_tenant_cost_report, export_tenant_usage, get_tenant_billing, list_platform_capabilities, list_delivery_adapters.

list_youtube_automations, list_telegram_automations, get_tenant_diagnostics, get_support_bundle, export_tenant_data, export_participant_data, list_workflows.

get_workflow, get_workflow_draft, list_workflow_versions, get_platform_policy, list_delivery_activity, list_connections, get_meta_configuration.

list_team_members, list_audit_history, list_resources, get_resource, list_resource_notifications, list_resource_templates.

list_resource_subscribers, get_waitlist_signup_activity, list_resource_fulfillments, list_funnel_events, get_funnel_summary, list_funnel_conversions.

get_funnel_conversion_summary, list_content_sources, list_content_source_syncs, preview_personalization, list_personalization_reviews.

list_webhook_endpoints, get_calendly_connection.

list_sms_consent, lookup_sms_consent, list_sms_consent_events,

audit_sms_disclosure, check_twilio_sms_connection.

list_instagram_inbox_threads, get_instagram_inbox_thread,

get_instagram_inbox_reply_eligibility.

Workflow and tenant mutations:

update_tenant_settings, save_dashboard_view, delete_dashboard_view, create_workflow, update_workflow, duplicate_workflow, bulk_update_workflows, bulk_pause_workflows (compatibility), archive_workflow, delete_workflow, pause_workflow.

resume_workflow, activate_workflow_draft, discard_workflow_draft, rollback_workflow_version, recover_instagram_delivery, request_meta_configuration_check, disconnect_connection, create_team_invitation, create_organization_invitation, resend_team_invitation, revoke_team_member, delete_data_subject.

start_instagram_oauth_connection starts the same sensitive, single-use,

10-minute Meta consent handoff as the REST route. It returns an authorization

URL for an owner or administrator to open and complete; it neither bypasses

Turnstile or login nor issues browser cookies, exposes passwords, or replaces

Meta's provider consent.

Instagram inbox mutations:

send_instagram_inbox_reply, save_instagram_inbox_draft,

assign_instagram_inbox_thread, add_instagram_inbox_note,

set_instagram_inbox_reminder, complete_instagram_inbox_reminder.

Webhook mutations:

create_webhook_endpoint, set_webhook_endpoint_enabled, delete_webhook_endpoint, connect_calendly, disconnect_calendly.

Resource and source mutations:

create_resource, create_resource_from_template, update_resource, verify_resource_destination, retry_resource_fulfillment, cancel_resource_fulfillment, create_content_source, sync_content_source, update_content_source, pause_content_source, resume_content_source, delete_content_source.

Adapter and personalization mutations:

upsert_youtube_automation, upsert_telegram_automation,

install_telegram_bot, connect_twilio_sms, send_sms,

connect_meta_account, preview_personalization,

decide_personalization_review, upsert_participant_context.

SMS consent mutations:

record_sms_consent, revoke_sms_consent.

Some MCP tools registered by the server are platform-operator operations and deliberately absent from the customer inventory. They require the protected system credential and cannot be unlocked by a customer role or a supplied tenant ID.

Exact-confirmation safety

Destructive and high-impact operations fail unless the confirmation matches the target. Common fields are:

An agent should fetch the target, show the intended operation, and obtain human approval before irreversible customer-data deletion.