DOCS · REFERENCE
Operation reference
Each operation below works the same way everywhere: POST /v1/operations/<name> on the HTTP API, the tool name_with_underscores on the MCP server, and sagot <name> in the CLI. Inputs are JSON; most operations take the workspaceId they act on. The machine-readable contract is openapi.json. New here? Start with the developer docs.
Access
access.info
Read public registration availability (closed alpha is the default) and whether the caller's session or credential is valid (signedIn). Requires no sign-in.
Waitlist
waitlist.join
Request alpha participation with contact consent. Does not create an account or send email. Requires no sign-in.
| Field | Type | Required |
|---|---|---|
name | string | yes |
email | string | yes |
company | string | yes |
useCase | string | yes |
consent | boolean | yes |
website | string | yes |
waitlist.list
Platform operators only: review the alpha queue, oldest first, with status and pagination. Requires read permission.
| Field | Type | Required |
|---|---|---|
status | "waiting" | "contacted" | "invited" | "admitted" | "closed" | no |
offset | integer | yes |
limit | integer | yes |
waitlist.update
Platform operators only: mark an applicant waiting, contacted or closed. Requires configure permission.
| Field | Type | Required |
|---|---|---|
id | UUID | yes |
status | "waiting" | "contacted" | "closed" | yes |
waitlist.delete
Platform operators only: permanently remove an applicant's waitlist information. Does not delete their account or invitations. Requires configure permission.
| Field | Type | Required |
|---|---|---|
id | UUID | yes |
Invitations
invitations.create
Platform operators only: issue an email-bound, single-use private invitation. Returns the token once; share privately. Does not send email. Replaces prior unused invitations for that email. Requires configure permission.
| Field | Type | Required |
|---|---|---|
email | string | yes |
expiresInDays | integer | yes |
invitations.list
Platform operators only: list invitation states without tokens, newest first. Requires read permission.
| Field | Type | Required |
|---|---|---|
offset | integer | yes |
limit | integer | yes |
invitations.revoke
Platform operators only: revoke an unused invitation. Existing accounts are unaffected. Requires configure permission.
| Field | Type | Required |
|---|---|---|
id | UUID | yes |
Account
account.register
Operation in the shared contract. Requires no sign-in.
| Field | Type | Required |
|---|---|---|
name | string | yes |
email | string | yes |
password | string | yes |
invitationToken | string | no |
memberInvitationToken | string | no |
account.login
Operation in the shared contract. Requires no sign-in.
| Field | Type | Required |
|---|---|---|
email | string | yes |
password | string | yes |
account.me
Operation in the shared contract. Requires read permission.
account.logout
Operation in the shared contract. Requires configure permission.
Workspaces
workspaces.create
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
name | string | yes |
workspaces.list
Operation in the shared contract. Requires read permission.
workspaces.update
Operation in the shared contract. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
name | string | yes |
Members
members.list
List the people in this workspace with their roles (viewer, editor, operator, admin, owner). Admins also see invitations and their status; tokens are never shown. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
members.invite
Admins: invite an email to this workspace with a role, optionally limited to agentIds (viewer/editor/operator only). SAGOT emails the invitation when email is configured; the one-time link path (/join#member=…) is also returned once as a fallback. The invitee signs in or creates an account with that email. Only the owner can invite admins. Re-inviting an email replaces its earlier pending invitation. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
email | string | yes |
role | "viewer" | "editor" | "operator" | "admin" | yes |
agentIds | UUID[] | null | no |
expiresInDays | integer | yes |
members.update
Admins: change a member's role and, with agentIds, limit a viewer/editor/operator to selected agents (null = all agents). Takes effect on their next request, including their API keys. The owner's role cannot change; only the owner grants or removes admin. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
accountId | UUID | yes |
role | "viewer" | "editor" | "operator" | "admin" | yes |
agentIds | UUID[] | null | no |
members.transfer
Owner only, signed-in session: make another member the owner. You become an admin; any agent limit on them is removed. The new owner is emailed. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
accountId | UUID | yes |
members.remove
Admins remove a member; any member may remove themselves to leave. The owner cannot be removed. Their sessions and API keys stop working in this workspace immediately. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
accountId | UUID | yes |
members.revoke
Admins: revoke a pending member invitation by id so its link stops working. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
members.preview
Public: show what a member invitation link grants (workspace, inviter, role, invited email, status) before accepting. Requires no sign-in.
| Field | Type | Required |
|---|---|---|
token | string | yes |
members.accept
Signed-in account session only: accept a member invitation issued to this account's email and join the workspace with its role. Requires configure permission.
| Field | Type | Required |
|---|---|---|
token | string | yes |
Credentials
credentials.create
Operation in the shared contract. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
name | string | yes |
scopes | "read" | "configure" | "publish" | "call" | "admin"[] | yes |
credentials.list
Operation in the shared contract. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
credentials.revoke
Operation in the shared contract. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Agents
agents.create
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
persona | object | yes |
agents.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
agents.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
agents.save
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
persona | object | yes |
agents.test
Validate the current draft and its integration. This is configuration validation, not a voice-quality score. Use a draft SIP call to hear the result. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
agents.publish
Publish a validated draft for new calls. Active calls keep their original snapshot. Requires publish permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
agents.pause
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
agents.rollback
Point new calls to a previous published version. Requires publish permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
version | UUID | yes |
agents.retire
Operation in the shared contract. Requires publish permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
version | UUID | yes |
Integrations
integrations.save
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | no |
revision | integer | no |
name | string | yes |
mode | "sandbox" | "https" | yes |
endpoint | string | yes |
reconciliationEndpoint | string | yes |
eventEndpoint | string | yes |
secret | string | no |
actionName | string | yes |
descriptionWhen the agent should use this action and what it accomplishes. | string | yes |
requiredFields | string[] | yes |
integrations.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
integrations.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
integrations.test
Exercise the connector with a test payload. Sandbox never writes to an external product. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
payload | object | yes |
integrations.disconnect
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Contacts
contacts.import
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
contacts | object[] | yes |
contacts.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
contacts.history
Review all retained calls, conversations, outcomes, actions, follow-ups and activity for one contact across agents in this workspace. Missing or deleted evidence is labeled. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
contacts.export
Export the contact's retained evidence as a readable Markdown or structured JSON audit snapshot. Export is logged; it does not create recordings or recover deleted content. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
format | "markdown" | "json" | yes |
contacts.update
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
name | string | yes |
source | string | yes |
eligibility | string | yes |
contacts.suppress
Permanently suppress this contact from new calls in this workspace. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
reason | string | yes |
Campaigns
campaigns.save
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | no |
revision | integer | no |
name | string | yes |
agentId | UUID | yes |
contactIds | UUID[] | yes |
budgetCentavos | integer | yes |
lineId | UUID | null | no |
campaigns.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
campaigns.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
campaigns.preview
Inspect eligible contacts, exclusion reasons and the maximum reserved cost without dialing. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
campaigns.start
Operation in the shared contract. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
campaigns.pause
Operation in the shared contract. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
campaigns.resume
Operation in the shared contract. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
campaigns.cancel
Operation in the shared contract. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Calls
calls.create
Queue one call on the workspace's bound route to an operator-allowlisted destination. Live prospect dialing is not enabled. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
agentId | UUID | yes |
contactId | UUID | yes |
idempotencyKey | string | yes |
draft | boolean | yes |
lineId | UUID | no |
calls.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
calls.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
calls.recording
Get recording availability and authenticated audio URL. Fetch that URL with the same bearer credential to play/download Ogg audio; CLI supports --output file. Older unrecorded calls have no audio. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
calls.cancel
Cancel a queued or active call. On a finished call with a scheduled automatic retry, cancels that retry instead. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Actions
actions.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
actions.reconcile
Query the owning system about an uncertain action. Does not repeat the business write. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Handoffs
handoffs.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
handoffs.update
Operation in the shared contract. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
status | "accepted" | "resolved" | "canceled" | yes |
owner | string | yes |
Events
events.list
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
limit | integer | yes |
cursor | UUID | no |
events.replay
Retry delivery of this event with its original event ID. Requires call permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Policies
policies.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
policies.update
Operation in the shared contract. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
revision | integer | yes |
policy | object | yes |
Usage
usage.get
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
Routes
routes.list
Deprecated alias of lines.list: offered routes with health and the workspace's default line as `bound`. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
routes.bind
Deprecated alias: add (if needed) and make default the line for this route; inboundAgentId as in lines.update. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
route | "sip-test" | "phone-gateway" | yes |
inboundAgentId | UUID | null | no |
routes.clearAlert
Deprecated alias of lines.clearAlert for the workspace's default line. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
Lines
lines.list
List this workspace's phone lines (provider, default, mode, test numbers, ring window, live health, inbound answering, telco warning) and the providers this deployment offers. Secrets are never returned. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
lines.get
Read one phone line with its live health and warning. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
lines.create
Add a phone line from an offered provider. Adding never dials. The first line becomes the default for new calls and campaigns. Lines start in test mode: only the line's test numbers can be called. A `gateway` line (your own computer + phone) returns a one-time `pairing.code` (30 minutes) that the SAGOT gateway app exchanges for its own credential; the code is shown only once. A `twilio` line connects your own Twilio account: pass accountSid, apiKeySid, apiKeySecret (a Standard API key; write-only) and the numbers to attach (lines.twilioNumbers lists them). SAGOT creates an Elastic SIP Trunk, a credential list, an origination URL and attaches the numbers in your account, records every object it created and removes exactly those when the line is deleted. Twilio bills the calls to your account. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
provider | "sandbox" | "legacy_gateway" | "gateway" | "twilio" | yes |
name | string | no |
isDefault | boolean | no |
accountSid | string | no |
apiKeySid | string | no |
apiKeySecret | string | no |
numbers | string[] | no |
callerId | string | no |
edge | "singapore" | "tokyo" | "sydney" | "ashburn" | "umatilla" | "dublin" | "frankfurt" | "sao-paulo" | no |
lines.twilioNumbers
Check a Twilio Standard API key (accountSid, apiKeySid, apiKeySecret) and list the account's voice-capable numbers and whether Twilio is reachable. Changes nothing and stores nothing. Use it before lines.create with provider twilio. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
accountSid | string | yes |
apiKeySid | string | yes |
apiKeySecret | string | yes |
lines.update
Rename a line, make it the default, choose the published inboundAgentId that answers its callers (gateway lines; null stops answering), set testNumbers (customer gateway and Twilio lines), rotatePairing to issue a new pairing code and sign the paired device out, or capacity (Twilio lines: concurrent calls 1–10; phone gateways and shared routes carry one call). The deployment also caps concurrent calls overall. Live mode is not available yet. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
revision | integer | yes |
name | string | no |
isDefault | boolean | no |
mode | "test" | "live" | no |
inboundAgentId | UUID | null | no |
testNumbers | string[] | no |
rotatePairing | boolean | no |
capacity | integer | no |
lines.test
Check a line's readiness without dialing: provider offered, health, test numbers. Use calls.create with lineId for a real test call. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
lines.clearAlert
Clear this line's telco warning after fixing the cause (for example topping up the gateway SIM). Held automatic retries and campaigns on this line resume. An answered call also clears it. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
lines.delete
Remove a phone line. Refused while it has active calls. For a Twilio line SAGOT first deletes the trunk, credentials and origination URL it created in your account and detaches your numbers (the numbers stay yours). Finished calls keep their history; scheduled retries on it are skipped. Another line becomes the default if needed. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Artifacts
artifacts.export
Operation in the shared contract. Requires read permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
artifacts.delete
Operation in the shared contract. Requires configure permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
Support
support.list
Workspace admins: SAGOT support access requests and grants for this workspace, with what staff read while access was active. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
support.approve
Workspace admins: approve a pending SAGOT support access request. The staff member gets read-only access for the requested hours, starting now. Nothing can be changed by staff. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
support.deny
Workspace admins: deny a pending SAGOT support access request. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |
support.revoke
Workspace admins: end active SAGOT support access immediately. Requires admin permission.
| Field | Type | Required |
|---|---|---|
workspaceId | UUID | yes |
id | UUID | yes |