Operations
Operations

Set integration OpenAPI spec

Set the OpenAPI 3.x spec that defines a custom HTTP integration's callable actions (the paths/operations an agent's tools can call). Pass the integration id (from list_workspace_integrations) and the spec as a JSON object. The spec is validated (must be OpenAPI 3.x with 'info' + 'paths') before it's stored; an invalid spec is rejected with the specific errors. No credentials go here; API keys and OAuth secrets are set separately via create_workspace_integration and Settings → Connections. Requires workspace-admin.

POST
/operations/set_workspace_integration_openapi

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/operations/set_workspace_integration_openapi" \  -H "Content-Type: application/json" \  -d '{    "workspace": "string",    "integrationId": "string",    "spec": {      "property1": null,      "property2": null    }  }'
{}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Set workflow function POST

Add or replace one function in the agent's workflow, matched by name within its slot. Functions are self-contained steps that run around the conversation: preCall functions run before the agent's first turn (kinds http, a request to any https endpoint; tool, one of this version's in-call tools; and app, an action of a connected app) and each result reaches the agent in its call context; callEnded (hang-up) functions run the moment the call ends, before analysis, and stop after 10 seconds (kinds http, sms, email and slack; they see {{disconnection_reason}}, {{call_status}} and {{call_duration_seconds}} but no analysis variables, and call_status is ended or error at hang-up; an outbound campaign or lead-callback call that rings out or is busy starts no conversation and runs only its callEnded functions, with disconnection_reason no_answer or busy, call_status not_connected and {{caller.number}} the number dialled); postCall functions run after the call is analysed (kinds http, tool, app, sms, email and slack). Each function sets `after` (names in the same slot it waits on; [] starts at once; a chain holds at most 4), optional `when` (all or any of: a variable rule such as {"kind":"variable","variable":"call_successful","op":"eq","value":"false"}, and on callEnded or postCall a disconnection_reason or call_status rule, or an early_hangup rule such as {"kind":"early_hangup","underSeconds":30}, which matches when the caller hung up within that many seconds, 5 to 600; a variable rule on a value with a fixed set takes eq, neq, exists or not_exists and one of its values: call_successful is true or false; user_sentiment is positive, neutral or negative; urgency is urgent or normal; caller_type is new_lead, existing or spam; call_outcome is handled, abandoned, dropped, transferred or unknown; disconnection_reason is agent_end_call, busy, caller_hangup, connection_lost, emergency, error, idle_timeout, injection_hangup, max_duration, moderation_hangup, no_answer, no_input_hangup, outside_hours, transfer_to_human, voicemail_detected or voicemail_reached; call_status is ended, error or not_connected; caller_is_team is true or false; call_duration_seconds also takes gt, lt, gte and lte with a number), `inputs` ({"param": {"mode":"value","value":"text with {{variable}} placeholders"}}; on postCall an input may instead be {"mode":"ai","prompt":"The caller's preferred callback time"}, which the call analysis fills from the call and leaves empty when the call does not say). On postCall an sms may set `sms.prompt` and an email `email.prompt` (such as "Thank the caller and confirm the job they booked"): the call analysis writes the text or body from it, and the written text or body is not sent. AI-filled inputs and messages count with the post-call fields against one limit of 20 analysis fields, and preCall and callEnded functions take neither. An http POST, PUT or PATCH may set `http.body`, a JSON template sent in place of the inputs; a {{variable}} inside a string is filled JSON-escaped, and one standing alone must hold a number, true, false or null. Without a body the inputs are sent as {name, args, call} unless `http.argsOnly` is true. An app function sets `app` ({"toolkit":"hubspot","action":"HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA"}; list_agent_connections names the toolkits and list_connector_tools the actions) and passes the action's parameters as `inputs`; each value is converted to the type the action declares. Saving an app function needs workspace-admin access and an app the workspace has connected; when the agent has no row for that app yet, it gets one that loads none of the app's tools during the call, so only the workflow runs the action. A function may also set `outputs.variables` (name to a dot path in the response, readable as {{name}} by later functions, the system prompt and post-call functions) and `outputs.types` (the type of an output by name, boolean or number, such as {"vip":"boolean"}; an output left out is text): a condition on a boolean output takes eq, neq, exists or not_exists with true or false, and one on a number output takes a number under gt, lt, gte and lte. Placeholders: agent variables, {{caller.number}} and the other {{caller.*}} fields, {{direction}}, {{channel}}, {{agent_number}}, {{call_id}}, outputs of functions this one waits on, and on postCall {{call_summary}}, {{call_successful}}, {{user_sentiment}}, {{disconnection_reason}}, {{call_status}} and the other call results, and the caller details the analysis extracts: {{customer_name}}, {{account_number}}, {{phone_number}}, {{email}}, {{address}}, {{issue_type}} and {{resolution}}, each post-call field declared with set_post_call_field, by its name, and {{transcript}} (the call as Caller: and Agent: lines, newest kept within 20,000 characters, empty when the agent keeps basic details only); on callEnded and postCall also each output an in-call HTTP tool keeps with set_tool_outputs. Never put a credential in a header, query, body or input: use a {{variable}} and set_secret_variable. A slack function may set `slack.channel` ({id, name} of a channel list_call_alerts returns under slackChannels); without one it posts to the workspace's first channel. Up to 15 functions per slot. Pass `previousName` to rename. Set `enabled` false to turn a function off without deleting it, or use set_workflow_function_enabled. Works on a draft, or on a published latest version when you pass draftFrom.

Rename workspace POST

Rename the operator's workspace once the real business name surfaces in the interview. Workspaces are named whatever the user typed at signup, often a placeholder like 'My Workspace'. Call this exactly once during onboarding, mid-interview, when you have a confident name. Changes the display name only, the slug stays stable, so existing agent handles and links keep working.