Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Retell. Agents and calls are pulled from your account on a schedule.

provider
string
required
Allowed value: "RETELL"
name
string
required

What the connection is called in Roark. At least 3 characters.

Required string length: 3 - 120
Example:

"Production Retell"

apiKey
string
required

The platform's API key. Checked against the platform before anything is stored. Stored encrypted and never returned.

Minimum string length: 1
capabilities
enum<string>[]

What the connection does. Defaults to PULL_AGENTS and PULL_CALLS, plus PUSH_AGENT_CONFIG on Retell, Vapi and ElevenLabs.

Minimum array length: 1

PULL_AGENTS imports the agents (and their prompts and tools) into Roark. PULL_CALLS imports production calls for analysis, and needs PULL_AGENTS on platforms that pull agents. PUSH_AGENT_CONFIG lets Roark write a verified fix back to the agent, only ever after a person applies it.

Available options:
PULL_AGENTS,
PULL_CALLS,
PUSH_AGENT_CONFIG
agentScope
enum<string>

ALL brings in every agent on the account. SELECTED brings in only agentIds and agentNames.

Available options:
ALL,
SELECTED
agentIds
string[]

The platform's own ids of the agents to bring in when agentScope is SELECTED. POST /v1/connections/agent/discover lists them.

Minimum string length: 1
agentNames
string[]

Agents to create by name rather than by id, for agents the platform does not list. On LiveKit Cloud this is the agent name your worker dispatches as.

Minimum string length: 1
autoSetUpAgents
boolean

When true, every agent this connection brings in is set up for testing as it arrives: Roark drafts its customer flows and metrics, the same as setting the agent up by hand. Defaults to false.

samplingRate
number

Fraction of production calls to import and analyse, from 0 to 1. Defaults to 1 (every call).

Required range: 0 <= x <= 1
Example:

1

Response

The connection

data
object
required

A connection to the platform a project’s agents run on. Credentials are never returned; the API key Roark mints for an SDK-driven platform is returned once, on create.

observerApiKey
string | null
required

For LIVEKIT_SELF_HOSTED and the Pipecat providers: the Roark API key your SDK reports calls with, bound to this connection. Returned only here; store it now. Null for every other provider, and if minting failed.