API reference
Build on the ServiceAgent API platform.
Use this page as the human-friendly API entry point for installs, widgets, CRM, booking, communications, AI agents, workflows, integrations, webhooks, realtime voice, and MCP. For machine-readable context, pair it with the curated public OpenAPI spec, llms.txt, and llms-full.txt.
Canonical docs-side API entry point
Use this route instead of the backend host for navigation. It is the stable human-readable landing page for API discovery, while the backend host stays focused on serving runtime traffic. Use the curated public OpenAPI export for external docs, SDK generation, and AI codegen.
Base URLs
Runtime API base: https://process.serviceagent.ai
Docs base: https://docs.serviceagent.ai
Voice stream: wss://process.serviceagent.ai/v1/voice/stream
What this page covers
Public and authenticated developer APIs that support real integrations.
CRM, scheduling, communications, AI agents, knowledge, workflows, payments, surveys, and reviews.
MCP and voice entry points used by AI tools and realtime apps.
Platform areas
The public API is organized by what developers want to build: embedded customer experiences, CRM sync, scheduling, AI agent operations, automation, communications, and revenue workflows. Use the generated reference below for exact paths and schemas.
Embed and onboard
Provision demo workspaces, claim installs, fetch widget config, and create public chat or booking sessions.
CRM system of record
Manage companies, contacts, deals, activities, tasks, imports, filters, enrichment, and customer intelligence.
Scheduling operations
Build around appointments, staff, locations, availability, conflicts, rescheduling, and calendar exports.
AI agents and knowledge
Create agents, configure channels and voice settings, sync knowledge, run tests, and publish customer-facing agents.
Inbox and communications
Read and act on inbox threads, messages, emails, templates, calls, transcripts, recordings, and communication analytics.
Integrations and automation
Connect third-party CRMs/calendars/task systems, map fields, sync data, generate workflows, and inspect workflow runs.
Revenue and reputation
Use payments, invoices, payment links, subscriptions, credits, reviews, review requests, and surveys.
Webhooks, MCP, and AI tools
Subscribe to events, inspect deliveries, replay failures, and let Cursor, Claude, or ChatGPT operate through MCP.
Generated public OpenAPI reference
This section is generated from the curated public OpenAPI export, not a hand-maintained endpoint list. The full backend contract remains separate for FE codegen and contract checks; the public export includes the stable and beta surfaces intended for external developers and AI codegen tools.
Public spec
1.0
430 operations across 25 groups.
Download
Use for SDK generation, docs rendering, and AI codegen.
Generation policy
Explicit allowlist only. Internal, admin, telemetry, and inbound provider webhook routes stay out.
CRM Activities
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/activities | stable | Get all activities |
| POST | /v1/activities | stable | Create a new activity |
| GET | /v1/activities/{id} | stable | Get activity by ID |
| PATCH | /v1/activities/{id} | stable | Update activity |
| DELETE | /v1/activities/{id} | stable | Delete activity |
AI Agents
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/agents | beta | List unified agents |
| POST | /v1/agents | beta | Create a unified agent |
| GET | /v1/agents/persona-templates | beta | List persona templates available for voice agent creation |
| GET | /v1/agents/persona-templates/{id} | beta | Fetch one persona template by id |
| GET | /v1/agents/post-call-rules/catalog | beta | List the post-call rules catalog for the rules editor |
| GET | /v1/agents/post-call-rules/templates | beta | List pre-curated post-call rule templates |
| POST | /v1/agents/post-call-rules/templates/{templateId}/apply-to-org | beta | Apply a post-call rule template to one or more agents |
| GET | /v1/agents/tool-catalog | beta | List the tool catalog for operator tool-scope UI |
| DELETE | /v1/agents/unified/{id} | beta | Legacy alias: delete a unified agent (soft delete) |
| GET | /v1/agents/voice-configs | beta | Legacy alias for voice config lookup (compat: GET /v1/agents/voice-configs?agentId=...) |
| GET | /v1/agents/{id} | beta | Get a unified agent |
| PUT | /v1/agents/{id} | beta | Update a unified agent |
| DELETE | /v1/agents/{id} | beta | Delete a unified agent (soft delete) |
| GET | /v1/agents/{id}/analytics | beta | Get agent analytics |
| POST | /v1/agents/{id}/channels/chat/disable | beta | Disable chat channel for an agent |
| POST | /v1/agents/{id}/channels/chat/enable | beta | Enable chat channel for an agent |
| POST | /v1/agents/{id}/channels/voice/disable | beta | Disable voice channel for an agent |
| POST | /v1/agents/{id}/channels/voice/enable | beta | Enable voice channel for an agent |
| PUT | /v1/agents/{id}/channels/{channel} | beta | Update a channel configuration |
| GET | /v1/agents/{id}/post-call-rule-executions | beta | Get a call's post-call rule execution log |
| GET | /v1/agents/{id}/post-call-rules | beta | List post-call rules for a voice agent |
| PUT | /v1/agents/{id}/post-call-rules | beta | Replace post-call rules for a voice agent |
| POST | /v1/agents/{id}/publish | beta | Publish an agent |
| POST | /v1/agents/{id}/sample-run | beta | Run a deterministic voice agent sample call |
| GET | /v1/agents/{id}/sample-runs/{runId} | beta | Fetch a deterministic voice agent sample-call result |
| POST | /v1/agents/{id}/sync-knowledge | beta | Sync knowledge base to enabled channels |
| POST | /v1/agents/{id}/test-call | beta | Initiate a test call to the user’s phone |
| GET | /v1/agents/{id}/test-call/{callId} | beta | Get test call status |
| POST | /v1/agents/{id}/test-call/{callId}/end | beta | End an ongoing test call (best effort) |
| GET | /v1/agents/{id}/voice-config | beta | Get voice agent config for a unified agent |
| PUT | /v1/agents/{id}/voice-config | beta | Create or update voice agent config for a unified agent |
| POST | /v1/agents/{id}/voice-config/dry-run | beta | Test Drive: rehearse a single turn against the agent config |
| POST | /v1/agents/{id}/voice-config/prompt-preview | beta | Inspect the compiled AIVA voice prompt for a unified agent |
| POST | /v1/agents/{id}/voice-config/publish | beta | Publish voice agent config |
| GET | /v1/agents/{id}/voice-config/publish-preview | beta | Customer-facing publish preview summary |
| GET | /v1/agents/{id}/voice-config/published-snapshot | beta | Get the last published prompt snapshot for this agent |
| POST | /v1/agents/{id}/voice-config/published-snapshot | beta | Upsert the published prompt snapshot baseline |
| GET | /v1/agents/{id}/voice-config/readiness | beta | Get publish-readiness report for a unified agent voice config |
| GET | /v1/ai/agents | beta | Get all AI agents for the organization |
| POST | /v1/ai/agents | beta | Create a new AI agent |
| GET | /v1/ai/agents/templates/{industry} | beta | Get industry-specific agent templates |
| GET | /v1/ai/agents/{id} | beta | Get a specific AI agent by ID |
| PATCH | /v1/ai/agents/{id} | beta | Update an AI agent |
| DELETE | /v1/ai/agents/{id} | beta | Delete an AI agent |
| GET | /v1/ai/agents/{id}/calls | beta | Get AI agent call history |
| GET | /v1/ai/agents/{id}/performance | beta | Get AI agent performance metrics |
| POST | /v1/ai/agents/{id}/test | beta | Test an AI agent with sample input |
AI Brain
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/ai/brain/context | beta | Get AI Brain context for chat/voice |
| POST | /v1/ai/brain/knowledge/search | beta | Search knowledge base with hybrid summary + chunk results |
| GET | /v1/ai/brain/profile | beta | Get business profile with coverage metrics |
| PUT | /v1/ai/brain/profile | beta | Update business profile and trigger AI sync |
| GET | /v1/ai/brain/profile/gaps | beta | Analyze profile and return improvement suggestions |
| POST | /v1/ai/brain/profile/sync | beta | Force re-sync of AI Brain without changing profile |
| POST | /v1/ai/brain/sync-services | beta | Sync service offerings into AI Brain profile |
Knowledge
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/ai/config/kb | beta | Get all knowledge base articles |
| POST | /v1/ai/config/kb | beta | Create a knowledge base article |
| GET | /v1/ai/config/kb/search/{query} | beta | Search knowledge base |
| GET | /v1/ai/config/kb/{id} | beta | Get a knowledge base article by ID |
| PATCH | /v1/ai/config/kb/{id} | beta | Update a knowledge base article |
| DELETE | /v1/ai/config/kb/{id} | beta | Delete a knowledge base article |
| GET | /v1/knowledge-base | beta | Alias: list knowledge base articles |
| POST | /v1/knowledge-base | beta | Alias: create knowledge base article |
| GET | /v1/knowledge-base/analytics | beta | Knowledge base analytics + recent queries |
| GET | /v1/knowledge-base/articles | beta | List org knowledge base articles (for agent picker) |
| PATCH | /v1/knowledge-base/{id} | beta | Alias: update knowledge base article |
| DELETE | /v1/knowledge-base/{id} | beta | Alias: delete knowledge base article |
| GET | /v1/knowledge-bases | beta | List knowledge bases |
| POST | /v1/knowledge-bases | beta | Create knowledge base |
| GET | /v1/knowledge-bases/{id} | beta | Get knowledge base details |
| DELETE | /v1/knowledge-bases/{id} | beta | Delete knowledge base |
| POST | /v1/knowledge-bases/{id}/documents | beta | Upload a knowledge base document (url/text/fileUrl) |
| DELETE | /v1/knowledge-bases/{id}/documents/{docId} | beta | Remove a knowledge base document |
| POST | /v1/knowledge-bases/{id}/sync | beta | Trigger re-indexing (embedding regeneration) for a knowledge base |
Widget
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/api/widget/{widgetKey}/config | stable | Fetch public configuration for an embeddable chat widget. |
| POST | /v1/api/widget/{widgetKey}/session | stable | Create a widget chat session. |
| GET | /v1/api/widget/{widgetKey}/session/{sessionId} | stable | Read a widget chat session. |
| POST | /v1/api/widget/{widgetKey}/session/{sessionId}/attachments | beta | Upload an attachment for a widget chat session. |
| POST | /v1/api/widget/{widgetKey}/session/{sessionId}/messages | stable | Send a message into a widget chat session. |
| POST | /v1/api/widget/{widgetKey}/session/{sessionId}/presence/read | beta | Mark widget session messages as read. |
| POST | /v1/api/widget/{widgetKey}/session/{sessionId}/presence/typing | beta | Send widget typing presence. |
Calendar
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/appointments | beta | Get all appointments |
| POST | /v1/appointments | beta | Create a new appointment |
| GET | /v1/appointments/analytics/by-service | beta | Top services by bookings / completed / revenue |
| GET | /v1/appointments/analytics/by-staff | beta | Top staff by bookings / completed / revenue |
| GET | /v1/appointments/analytics/export | beta | Export appointment analytics as CSV |
| GET | /v1/appointments/analytics/peak-hours | beta | Peak booking hours (hour-of-day histogram) |
| GET | /v1/appointments/analytics/summary | beta | Appointment analytics summary |
| POST | /v1/appointments/best-staff | beta | Find best staff assignment |
| GET | /v1/appointments/calendar-overview | beta | Get calendar overview for date range |
| GET | /v1/appointments/calendar/staff/{staffId} | beta | Get appointments for specific staff member in date range |
| GET | /v1/appointments/conflicts/check | beta | Check for scheduling conflicts |
| GET | /v1/appointments/overview | beta | Get calendar overview for date range |
| GET | /v1/appointments/slots/available | beta | Find available time slots |
| GET | /v1/appointments/{id} | beta | Get an appointment by ID |
| PATCH | /v1/appointments/{id} | beta | Update an appointment |
| DELETE | /v1/appointments/{id} | beta | Cancel an appointment |
| POST | /v1/appointments/{id}/cancel | beta | Cancel an appointment (alias) |
| GET | /v1/appointments/{id}/ics | beta | Download ICS file for appointment |
| PATCH | /v1/appointments/{id}/instance | beta | Update a single recurring appointment instance |
| DELETE | /v1/appointments/{id}/instance | beta | Delete a single recurring appointment instance |
| POST | /v1/appointments/{id}/reschedule | beta | Reschedule an appointment |
| GET | /v1/appointments/{id}/series | beta | Get recurring appointment series |
| POST | /v1/appointments/{id}/transfer | beta | Transfer an appointment to another location |
| GET | /v1/staff | beta | Get all staff members |
| POST | /v1/staff | beta | Create a new staff member |
| GET | /v1/staff/{id} | beta | Get a staff member by ID |
| PATCH | /v1/staff/{id} | beta | Update a staff member |
| DELETE | /v1/staff/{id} | beta | Delete a staff member |
| GET | /v1/staff/{id}/availability | beta | Get staff member availability for a date |
| GET | /v1/staff/{id}/breaks | beta | Get staff breaks |
| POST | /v1/staff/{id}/breaks | beta | Create staff break |
| DELETE | /v1/staff/{id}/breaks/{breakId} | beta | Delete staff break |
| GET | /v1/staff/{id}/time-off | beta | Get time off requests for staff |
| POST | /v1/staff/{id}/time-off | beta | Create time off request |
| PATCH | /v1/staff/{id}/time-off/{timeOffId} | beta | Update time off request |
| DELETE | /v1/staff/{id}/time-off/{timeOffId} | beta | Delete time off request |
| GET | /v1/staff/{id}/working-hours | beta | Get weekly working hours for staff |
| POST | /v1/staff/{id}/working-hours | beta | Set working hours for staff |
Auth
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/auth/api-keys | stable | List API keys |
| POST | /v1/auth/api-keys | stable | Create API key |
| DELETE | /v1/auth/api-keys/{id} | stable | Revoke API key |
| POST | /v1/auth/api-keys/{id}/rotate | stable | Rotate API key secret |
Calls
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/calls | beta | Get all calls |
| POST | /v1/calls/batch-analyze-sentiment | beta | Batch analyze sentiment |
| POST | /v1/calls/outbound | beta | Initiate an outbound call |
| GET | /v1/calls/unified | beta | List unified calls across voice providers, AIVA, and Dialer |
| GET | /v1/calls/unified/active | beta | List active unified calls for realtime dashboard |
| GET | /v1/calls/unified/analytics | beta | Get unified call analytics across all sources |
| GET | /v1/calls/unified/analytics/export | beta | Export unified call analytics as CSV |
| GET | /v1/calls/unified/{callId} | beta | Get unified call detail by call ID |
| POST | /v1/calls/{callId}/analyze-sentiment | beta | Analyze call sentiment |
CRM Companies
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/companies | stable | Get all companies |
| POST | /v1/companies | stable | Create a new company |
| POST | /v1/companies/bulk-update | stable | Bulk update companies |
| POST | /v1/companies/merge | stable | Merge companies |
| GET | /v1/companies/{id} | stable | Get a company by ID |
| PATCH | /v1/companies/{id} | stable | Update a company |
| DELETE | /v1/companies/{id} | stable | Delete a company |
CRM Contacts
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/contacts | beta | Get all contacts |
| POST | /v1/contacts | beta | Create a new contact |
| POST | /v1/contacts/bulk-update | beta | Bulk update contacts |
| POST | /v1/contacts/dedupe | beta | Deduplicate contacts |
| POST | /v1/contacts/enrichment/batch | beta | Batch contact enrichment |
| POST | /v1/contacts/export | beta | Export contacts (csv/pdf) |
| GET | /v1/contacts/export-csv | beta | Export contacts to CSV |
| GET | /v1/contacts/filters | beta | List saved filters |
| POST | /v1/contacts/filters | beta | Create saved filter |
| PUT | /v1/contacts/filters/{id} | beta | Update saved filter |
| PATCH | /v1/contacts/filters/{id} | beta | Update saved filter (alias) |
| DELETE | /v1/contacts/filters/{id} | beta | Delete saved filter |
| POST | /v1/contacts/filters/{id}/run | beta | Execute saved filter and return matching records |
| POST | /v1/contacts/import-csv/analyze | beta | Analyze CSV import file |
| POST | /v1/contacts/import-csv/execute | beta | Execute CSV contact import |
| POST | /v1/contacts/import-csv/execute-hybrid | beta | Execute hybrid CSV contact import |
| POST | /v1/contacts/import-csv/preview | beta | Preview hybrid CSV contact import |
| GET | /v1/contacts/import-csv/review-tasks | beta | List open CSV import review tasks |
| GET | /v1/contacts/import-csv/review-tasks/{taskId} | beta | Get a CSV import review task with candidates |
| POST | /v1/contacts/import-csv/review-tasks/{taskId}/resolve | beta | Resolve a CSV import review task (merge/create/ignore) |
| GET | /v1/contacts/lifecycle-stages | beta | List lifecycle stages for the organization |
| POST | /v1/contacts/lifecycle-stages/apply-preset | beta | Apply a lifecycle preset to rename and reorder stages |
| GET | /v1/contacts/lifecycle-stages/presets/list | beta | List available lifecycle stage presets |
| PATCH | /v1/contacts/lifecycle-stages/{id} | beta | Update lifecycle stage properties (rename, probability, routing) |
| PATCH | /v1/contacts/{id} | beta | Update a contact |
| DELETE | /v1/contacts/{id} | beta | Delete a contact |
| PATCH | /v1/contacts/{id}/behavioral-profile | beta | Update behavioral profile |
| PATCH | /v1/contacts/{id}/contextual-profile | beta | Update contextual profile |
| GET | /v1/contacts/{id}/enrichment | beta | Get contact enrichment |
| GET | /v1/contacts/{id}/insights | beta | Get contact insights |
| DELETE | /v1/contacts/{id}/insights/{insightId} | beta | Dismiss an insight |
| POST | /v1/contacts/{id}/insights/{insightId}/action | beta | Mark insight action as taken |
| GET | /v1/contacts/{id}/intelligence | beta | Get contact intelligence data |
| POST | /v1/contacts/{id}/intelligence/refresh | beta | Refresh contact intelligence |
| GET | /v1/contacts/{id}/network | beta | Get contact network |
| GET | /v1/contacts/{id}/predictions | beta | Get predictive analytics |
| PATCH | /v1/contacts/{id}/predictive-profile | beta | Update predictive profile |
| PATCH | /v1/contacts/{id}/relationship-profile | beta | Update relationship profile |
| GET | /v1/contacts/{id}/relationships | beta | Get contact relationships |
| GET | /v1/contacts/{id}/scores | beta | Get behavioral scores |
| POST | /v1/contacts/{id}/scores/calculate | beta | Recalculate behavioral scores |
| GET | /v1/contacts/{id}/timeline | beta | Get contact timeline |
| POST | /v1/contacts/{id}/timeline | beta | Add timeline event |
CRM Deals
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/deals | stable | Get all deals |
| POST | /v1/deals | stable | Create a new deal |
| GET | /v1/deals/analytics | stable | Get deal analytics for a period |
| POST | /v1/deals/bulk-update | stable | Bulk update deals |
| GET | /v1/deals/{id} | stable | Get a deal by ID |
| PUT | /v1/deals/{id} | stable | Update a deal (PUT) |
| PATCH | /v1/deals/{id} | stable | Update a deal |
| DELETE | /v1/deals/{id} | stable | Delete a deal |
| POST | /v1/deals/{id}/transfer | stable | Transfer a deal to another location |
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/emails | beta | Get email thread/history |
| GET | /v1/emails/analytics/overview | beta | Get email analytics overview |
| POST | /v1/emails/attachments | beta | Upload an email attachment (spec alias) |
| POST | /v1/emails/bulk-send | beta | Send bulk emails |
| POST | /v1/emails/send | beta | Send individual email |
| GET | /v1/emails/templates | beta | Get all email templates |
| POST | /v1/emails/templates | beta | Create email template |
| GET | /v1/emails/templates/industry/{industry} | beta | Get industry-specific template suggestions |
| GET | /v1/emails/templates/{id} | beta | Get single email template |
| PUT | /v1/emails/templates/{id} | beta | Update email template |
| DELETE | /v1/emails/templates/{id} | beta | Delete email template |
| GET | /v1/emails/templates/{id}/analytics | beta | Get template analytics |
| POST | /v1/emails/upload-attachment | beta | Upload an email attachment |
| GET | /v1/emails/{id} | beta | Get single email details |
Inbox
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/inbox/messages | beta | Get messages |
| POST | /v1/inbox/messages | beta | Send a message |
| POST | /v1/inbox/telegram/connect-link | beta | Create Telegram connect link for current user |
| GET | /v1/inbox/telegram/connections | beta | List Telegram chats connected by current user |
| DELETE | /v1/inbox/telegram/connections/{chatId} | beta | Disconnect a Telegram chat from current user |
| GET | /v1/inbox/threads | beta | Get all message threads |
| POST | /v1/inbox/threads | beta | Create a new message thread |
| GET | /v1/inbox/threads/{id} | beta | Get a message thread by ID |
Install
| Method | Path | Stability | Summary |
|---|---|---|---|
| POST | /v1/install/exchange | stable | Exchange install token for API key (server-only) |
| POST | /v1/install/magic-link/send | stable | Send magic link to claim workspace (passwordless) |
| POST | /v1/install/magic-link/verify | stable | Verify magic link and complete claim |
| POST | /v1/install/start | stable | Start instant install: create demo workspace + chat widget |
| GET | /v1/install/status | stable | Check install session status by token |
Integrations
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/integrations | beta | Get all integrations for organization |
| POST | /v1/integrations | beta | Create a new CRM integration |
| GET | /v1/integrations/asana/projects | beta | Get Asana projects |
| POST | /v1/integrations/asana/projects | beta | Create Asana project |
| GET | /v1/integrations/asana/projects/{projectId}/tasks | beta | Get Asana project tasks |
| POST | /v1/integrations/asana/tasks | beta | Create Asana task |
| PATCH | /v1/integrations/asana/tasks/{taskId} | beta | Update Asana task |
| GET | /v1/integrations/asana/workspaces | beta | Get Asana workspaces |
| GET | /v1/integrations/available | beta | List available integrations with metadata |
| GET | /v1/integrations/available-crms | beta | Get list of available CRM types |
| GET | /v1/integrations/calendar/available | beta | List available calendar integrations |
| GET | /v1/integrations/calendly/event-types | beta | Get Calendly event types |
| GET | /v1/integrations/calendly/scheduled-events | beta | Get Calendly scheduled events |
| GET | /v1/integrations/calendly/scheduled-events/{eventId}/invitees | beta | Get Calendly invitees for an event |
| GET | /v1/integrations/catalog | beta | List integration catalog with tier + connection metadata |
| POST | /v1/integrations/connect | beta | Connect a new integration (OAuth or API-key) |
| GET | /v1/integrations/health | beta | Get all integrations health status |
| GET | /v1/integrations/health/summary | beta | Get health status of all integrations |
| POST | /v1/integrations/sync-all | beta | Sync all active integrations |
| GET | /v1/integrations/{crmType}/appointments | beta | Get CRM appointments |
| POST | /v1/integrations/{crmType}/appointments | beta | Create CRM appointment |
| GET | /v1/integrations/{crmType}/contacts | beta | Get CRM contacts |
| POST | /v1/integrations/{crmType}/contacts | beta | Create CRM contact |
| PATCH | /v1/integrations/{crmType}/contacts/{contactId} | beta | Update CRM contact |
| GET | /v1/integrations/{crmType}/deals | beta | Get CRM deals |
| POST | /v1/integrations/{crmType}/deals | beta | Create CRM deal |
| PATCH | /v1/integrations/{crmType}/deals/{dealId} | beta | Update CRM deal |
| GET | /v1/integrations/{crmType}/field-mappings | beta | Get field mappings for integration |
| PATCH | /v1/integrations/{crmType}/field-mappings | beta | Update field mappings for integration |
| GET | /v1/integrations/{crmType}/metadata | beta | Get CRM metadata and capabilities |
| POST | /v1/integrations/{crmType}/oauth/callback | beta | Handle OAuth callback |
| POST | /v1/integrations/{crmType}/oauth/initiate | beta | Initiate OAuth flow |
| GET | /v1/integrations/{crmType}/status | beta | Get integration status and health |
| POST | /v1/integrations/{crmType}/sync | beta | Sync data with CRM |
| POST | /v1/integrations/{crmType}/validate-credentials | beta | Validate CRM credentials |
Locations
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/locations | beta | Get all locations |
| POST | /v1/locations | beta | Create a new location |
| POST | /v1/locations/service-request | beta | Create a public service request for unserved areas |
| GET | /v1/locations/{id} | beta | Get a location by ID |
| PATCH | /v1/locations/{id} | beta | Update a location |
| DELETE | /v1/locations/{id} | beta | Delete a location |
| GET | /v1/locations/{id}/availability | beta | Get location availability |
| POST | /v1/locations/{id}/default | beta | Set organization default location |
| GET | /v1/locations/{id}/staff | beta | List staff assigned to this location |
| POST | /v1/locations/{id}/staff | beta | Replace staff assignments for this location |
MCP
| Method | Path | Stability | Summary |
|---|---|---|---|
| POST | /v1/mcp | stable | Handle MCP protocol messages (JSON-RPC 2.0) via Streamable HTTP transport |
| POST | /v1/mcp/tools | stable | Execute MCP tool |
| POST | /v1/mcp/tools/list | stable | List available MCP tools |
Payments
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/payments/analytics | beta | Get payment analytics |
| GET | /v1/payments/analytics/forecast | beta | Get revenue forecast |
| GET | /v1/payments/analytics/trends | beta | Get invoice trends |
| GET | /v1/payments/connect/account | beta | Get Stripe Connect account for organization |
| POST | /v1/payments/connect/account | beta | Create Stripe Connect account |
| DELETE | /v1/payments/connect/account | beta | Disconnect Stripe Connect account |
| POST | /v1/payments/connect/account-link | beta | Create Stripe Connect account link (legacy route) |
| GET | /v1/payments/connect/account-status | beta | Get Stripe Connect account status (wiring guide route) |
| POST | /v1/payments/connect/account/link | beta | Create Stripe Connect account link |
| GET | /v1/payments/connect/account/status | beta | Get Stripe Connect account status for current organization |
| GET | /v1/payments/connect/balance | beta | Get connected account balance |
| POST | /v1/payments/connect/create-account | beta | Create Stripe Connect account (wiring guide route) |
| POST | /v1/payments/connect/create-account-link | beta | Create Stripe Connect account link (wiring guide route) |
| POST | /v1/payments/connect/create-payment-link | beta | Create a payment link for a customer (wiring guide route) |
| POST | /v1/payments/connect/payment-links | beta | Create payment link routed through connected account |
| GET | /v1/payments/connect/payouts | beta | List payouts for connected account |
| POST | /v1/payments/connect/payouts | beta | Create a payout to the connected account |
| POST | /v1/payments/credits/auto-reload | beta | Configure auto-reload settings |
| GET | /v1/payments/credits/balance | beta | Alias: get credit balance |
| POST | /v1/payments/credits/check-balance | beta | Check if organization has enough credits for an action |
| POST | /v1/payments/credits/check-reload | beta | Check and process auto-reload if needed |
| POST | /v1/payments/credits/checkout | beta | Create credit checkout session (alias route) |
| GET | /v1/payments/credits/packages | beta | Get available credit packages |
| POST | /v1/payments/credits/purchase | beta | Purchase credits |
| GET | /v1/payments/credits/transactions | beta | Get credit transaction history (paged) |
| GET | /v1/payments/credits/wallet | beta | Get credit wallet balance and summary |
| POST | /v1/payments/customers | beta | Create Stripe customer |
| GET | /v1/payments/customers/{id} | beta | Get Stripe customer |
| GET | /v1/payments/invoice-preview | beta | Get invoice preview with sample data |
| GET | /v1/payments/invoice-templates | beta | Get available invoice templates |
| GET | /v1/payments/invoices | beta | Get all invoices |
| POST | /v1/payments/invoices | beta | Create invoice |
| GET | /v1/payments/invoices/branding | beta | Get invoice branding settings |
| PATCH | /v1/payments/invoices/branding | beta | Update invoice branding settings |
| POST | /v1/payments/invoices/builder | beta | Create invoice using builder (free feature) |
| DELETE | /v1/payments/invoices/{id} | beta | Delete invoice |
| POST | /v1/payments/invoices/{id}/finalize | beta | Finalize invoice |
| POST | /v1/payments/invoices/{id}/mark-paid | beta | Manually mark invoice as paid |
| POST | /v1/payments/invoices/{id}/payment-link | beta | Generate payment link for invoice |
| GET | /v1/payments/invoices/{id}/payment-status | beta | Get invoice payment status |
| GET | /v1/payments/invoices/{id}/pdf | beta | Generate invoice PDF |
| POST | /v1/payments/invoices/{id}/send | beta | Send invoice |
| POST | /v1/payments/invoices/{id}/send-email | beta | Send invoice via email |
| POST | /v1/payments/payment-links | beta | Create payment link |
| GET | /v1/payments/payment-methods | beta | List saved payment methods for auto-reload |
| POST | /v1/payments/payment-methods | beta | Save payment method for auto-reload |
| POST | /v1/payments/payment-methods/setup-intent | beta | Create setup intent for saving payment method |
| POST | /v1/payments/payment-methods/{id}/default | beta | Set a payment method as default for auto-reload |
| POST | /v1/payments/refunds | beta | Create refund |
| POST | /v1/payments/subscriptions | beta | Create subscription |
| DELETE | /v1/payments/subscriptions | beta | Cancel subscription |
| POST | /v1/payments/subscriptions/billing-portal | beta | Get billing portal URL |
| GET | /v1/payments/subscriptions/current | beta | Get current subscription |
| GET | /v1/payments/subscriptions/plans | beta | Get available subscription plans |
| GET | /v1/payments/subscriptions/usage | beta | Get subscription usage analytics |
| PUT | /v1/payments/subscriptions/{planId} | beta | Update subscription plan |
| POST | /v1/payments/upload/logo | beta | Upload logo for invoice branding |
Booking
| Method | Path | Stability | Summary |
|---|---|---|---|
| POST | /v1/public/book/{bookingKey}/appointments | stable | Create appointment via public booking (booking key) |
| GET | /v1/public/book/{bookingKey}/slots | stable | Get available booking slots by booking key |
| POST | /v1/public/book/{bookingKey}/upload-photos | beta | Upload booking photos through Filestack (backend proxy) |
Reviews
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/reviews | beta | List reviews for the Reviews Inbox |
| GET | /v1/reviews/counts | beta | Get review inbox counts for badges/filters |
| POST | /v1/reviews/import | beta | Import reviews from external sources (e.g., Trustpilot/Clutch) via API |
| POST | /v1/reviews/ingest | beta | Trigger review ingestion for all or specific listing connections |
| GET | /v1/reviews/metrics/summary | beta | Get basic aggregate metrics for the Reviews dashboard (proxy) |
| GET | /v1/reviews/providers | beta | List supported review providers/sources and their capabilities |
| GET | /v1/reviews/request-settings | beta | Get review request settings for organization or location |
| PUT | /v1/reviews/request-settings | beta | Update review request settings |
| GET | /v1/reviews/requests | beta | List review requests |
| POST | /v1/reviews/requests | beta | Create manual review request(s) |
| GET | /v1/reviews/{reviewId} | beta | Get a single review (Inbox detail) |
| GET | /v1/reviews/{reviewId}/comments | beta | List internal comments/notes for a review |
| POST | /v1/reviews/{reviewId}/comments | beta | Add an internal comment/note to a review |
| PATCH | /v1/reviews/{reviewId}/reply | beta | Save a reply to a review (and mark responded). Publishing is provider-dependent. |
| POST | /v1/reviews/{reviewId}/reply-draft | beta | Generate an AI reply draft for a review (manual or publish flow) |
| POST | /v1/reviews/{reviewId}/view | beta | Mark a review as viewed (org-level, MVP) |
| PATCH | /v1/reviews/{reviewId}/workflow | beta | Update review workflow fields (status/assignee) |
Surveys
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/surveys | beta | List surveys (alias to survey templates) |
| POST | /v1/surveys | beta | Create survey (template) |
| GET | /v1/surveys/campaigns | beta | List survey campaigns |
| POST | /v1/surveys/campaigns | beta | Create a new survey campaign |
| GET | /v1/surveys/campaigns/{campaignId} | beta | Get campaign with triggers |
| PUT | /v1/surveys/campaigns/{campaignId} | beta | Update campaign configuration |
| POST | /v1/surveys/campaigns/{campaignId}/triggers | beta | Create trigger for campaign |
| PUT | /v1/surveys/campaigns/{campaignId}/triggers/{triggerId} | beta | Update trigger configuration |
| GET | /v1/surveys/invitations | beta | List survey invitations |
| POST | /v1/surveys/invitations/manual | beta | Create a manual survey invitation |
| GET | /v1/surveys/invitations/{invitationId} | beta | Get a specific invitation |
| PATCH | /v1/surveys/invitations/{invitationId}/cancel | beta | Cancel an invitation |
| PATCH | /v1/surveys/invitations/{invitationId}/reschedule | beta | Reschedule a queued invitation |
| POST | /v1/surveys/invitations/{invitationId}/resend | beta | Resend an invitation |
| GET | /v1/surveys/metrics/breakdown | beta | Get survey metrics breakdown by dimension |
| GET | /v1/surveys/metrics/overview | beta | Get survey performance overview |
| GET | /v1/surveys/responses | beta | List survey responses |
| POST | /v1/surveys/responses | beta | Record a response manually (e.g., admin input) |
| GET | /v1/surveys/responses/{responseId} | beta | Get a single response |
| GET | /v1/surveys/templates | beta | List survey templates for the organization |
| POST | /v1/surveys/templates | beta | Create a new survey template |
| GET | /v1/surveys/templates/{templateId} | beta | Get a single survey template |
| PUT | /v1/surveys/templates/{templateId} | beta | Update an existing survey template |
| POST | /v1/surveys/templates/{templateId}/duplicate | beta | Duplicate a survey template |
| PATCH | /v1/surveys/templates/{templateId}/status | beta | Enable or disable a survey template |
| GET | /v1/surveys/{id} | beta | Get survey (template) with questions |
| PATCH | /v1/surveys/{id} | beta | Update survey (template) |
| DELETE | /v1/surveys/{id} | beta | Delete survey (template) |
| POST | /v1/surveys/{id}/publish | beta | Publish survey (generate share URL + embed code) |
| GET | /v1/surveys/{id}/responses | beta | List survey responses (by template id) |
CRM Tasks
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/tasks | stable | Get all tasks |
| POST | /v1/tasks | stable | Create a new task |
| GET | /v1/tasks/count | stable | Get task count (useful for notifications/badges) |
| GET | /v1/tasks/{id} | stable | Get task by ID |
| PATCH | /v1/tasks/{id} | stable | Update task |
| DELETE | /v1/tasks/{id} | stable | Delete task |
Voice
| Method | Path | Stability | Summary |
|---|---|---|---|
| POST | /v1/voice/browser/token | beta | Create a Twilio Voice Client token (browser WebRTC calling) |
| GET | /v1/voice/preview/voices | beta | List available voice preview voices |
Webhooks
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/webhooks/deliveries | stable | Get webhook delivery history |
| POST | /v1/webhooks/deliveries/{id}/replay | stable | Replay webhook delivery |
| GET | /v1/webhooks/endpoints | stable | Get all webhook endpoints |
| POST | /v1/webhooks/endpoints | stable | Create webhook endpoint |
| GET | /v1/webhooks/endpoints/{id} | stable | Get webhook endpoint by ID |
| PATCH | /v1/webhooks/endpoints/{id} | stable | Update webhook endpoint |
| DELETE | /v1/webhooks/endpoints/{id} | stable | Delete webhook endpoint |
| POST | /v1/webhooks/endpoints/{id}/test | stable | Test webhook endpoint |
Workflows
| Method | Path | Stability | Summary |
|---|---|---|---|
| GET | /v1/workflow-actions | beta | List available workflow actions |
| GET | /v1/workflow-templates | beta | List workflow templates |
| GET | /v1/workflow-templates/{id} | beta | Get workflow template |
| POST | /v1/workflow-templates/{id}/use | beta | Create workflow from template |
| GET | /v1/workflows | beta | Get all workflows |
| POST | /v1/workflows | beta | Create a new workflow |
| POST | /v1/workflows/advisor/apply | beta | Create a workflow from a suggestion/template |
| POST | /v1/workflows/advisor/suggest | beta | Suggest workflows based on a natural language prompt |
| POST | /v1/workflows/ai/generate | beta | Generate workflow graph from natural language prompt |
| POST | /v1/workflows/ai/refine | beta | Refine an existing workflow with AI instruction |
| POST | /v1/workflows/ai/validate | beta | Validate AI-generated or edited workflow graph |
| GET | /v1/workflows/runs/failed | beta | List failed workflow runs (DLQ-like inbox) |
| GET | /v1/workflows/runs/{runId} | beta | Get a workflow run by ID |
| POST | /v1/workflows/runs/{runId}/cancel | beta | Cancel a workflow run |
| POST | /v1/workflows/runs/{runId}/retry | beta | Retry a workflow run by creating a new run |
| GET | /v1/workflows/schema | beta | Get workflow builder schema for AI + UI |
| GET | /v1/workflows/templates | beta | Get workflow template gallery for current organization |
| POST | /v1/workflows/templates/batch | beta | Upsert workflow templates in batch |
| POST | /v1/workflows/templates/batch-create | beta | Batch create workflows from templates for organization |
| GET | /v1/workflows/templates/categories/{industry} | beta | Get workflow categories for industry |
| POST | /v1/workflows/templates/sentiment-templates/create | beta | Create all 5 sentiment workflow templates for organization |
| GET | /v1/workflows/templates/{id}/executions | beta | Get workflow execution history |
| POST | /v1/workflows/templates/{id}/test | beta | Test workflow execution |
| GET | /v1/workflows/templates/{industry} | beta | Get industry-specific workflow templates |
| POST | /v1/workflows/templates/{templateId}/instantiate | beta | Instantiate a workflow from a template |
| GET | /v1/workflows/{id} | beta | Get a workflow by ID |
| PUT | /v1/workflows/{id} | beta | Replace/update a workflow |
| PATCH | /v1/workflows/{id} | beta | Update a workflow |
| DELETE | /v1/workflows/{id} | beta | Archive a workflow |
| POST | /v1/workflows/{id}/activate | beta | Activate a workflow |
| POST | /v1/workflows/{id}/deactivate | beta | Deactivate a workflow |
| POST | /v1/workflows/{id}/dry-run | beta | Dry-run a workflow with synthetic trigger data |
| POST | /v1/workflows/{id}/duplicate | beta | Duplicate a workflow |
| GET | /v1/workflows/{id}/logs | beta | Get workflow logs |
| GET | /v1/workflows/{id}/runs | beta | Get workflow runs |
| POST | /v1/workflows/{id}/trigger | beta | Trigger a workflow manually |
| GET | /v1/workflows/{workflowId}/executions/{executionId} | beta | Get a single workflow execution (frontend polling contract) |
Public endpoints
These are the fastest routes to understand if you are embedding widgets, creating booking experiences, or provisioning an install flow without a custom backend first.
| Method | Path | Use it for |
|---|---|---|
| POST | /v1/install/start | Provision a demo widget or starter install flow. |
| GET | /v1/api/widget/:widgetKey/config | Fetch public widget configuration for a widget key. |
| POST | /v1/api/widget/:widgetKey/session | Create a public chat session for widget-driven conversations. |
| GET | /v1/public/book/:bookingKey/slots | Return available booking slots for a public booking key. |
| POST | /v1/public/book/:bookingKey/appointments | Create a public booking appointment. |
Voice and MCP entry points
| Protocol | Path | Use it for |
|---|---|---|
| POST | /v1/mcp | Model Context Protocol server endpoint for Cursor, Claude, and other MCP clients. |
| GET | /.well-known/oauth-authorization-server | OAuth discovery metadata for MCP and secure client setup. |
| WSS | /v1/voice/stream | Realtime voice transport endpoint for low-latency audio sessions. |
Authenticated endpoints
These routes require a ServiceAgent API key or signed-in JWT. Start with a test key from Quickstart, then move to the SDK when your integration grows beyond one or two calls.
| Method | Path | Use it for |
|---|---|---|
| GET | /v1/webhooks/endpoints | List webhook endpoints with pagination metadata. |
| POST | /v1/webhooks/endpoints | Create a signed webhook endpoint for event delivery. |
| GET | /v1/webhooks/deliveries | Inspect webhook delivery attempts and retry status. |
| POST | /v1/auth/api-keys | Create scoped API keys for backend integrations. |
Auth and private APIs
For authenticated backend workflows, prefer the typed SDKs instead of stitching private routes together by hand. The SDKs give you stronger defaults, clearer auth handling, and a much better path for AI codegen tools.
Need an API key? See Quickstart → Get an API key.
- Use @serviceagent/sdk for server-to-server access.
- Use @serviceagent/nextjs when your app is already on Next.js and needs frontend plus server helpers.
- Use @serviceagent/mcp when Cursor, Claude, or ChatGPT should drive setup and operations.
Recommended integration path
Start with Quickstart if you want the shortest working path.
Move to Packages when you need the right SDK or UI layer for your stack.
Use Prompt Builder when you want Cursor or Claude to generate integration code with the right endpoints and implementation steps.