Connectors
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
Outside apps, such as Slack, Notion or Google Drive, that a person connects so the assistant can look things up in them and act there. A connector belongs to one person (account) or to the workspace (workspace).
GET/connector-apps
List apps that can be connected
The catalogue of apps that can be connected, most used first, as the Browse tab of the Connectors page shows it. Narrow it with search or category.
Requires the connectors:read scope.
Query parameters
searchstringWords to look for in the name or the description.
categorystringA category slug from the catalogue, to list only the apps in it.
limitintegerRows per page, 1 to 60.
At least 1At most 60Default24cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
A page of apps.
Errors
- 503
connectors_unavailable: connectors are not switched on.connector_provider_failed: the connection service did not answer.
The errors every operation can return400401403404422500Error catalog
Also available in
- TypeScript
connectors.listApps()connectors.listAllApps()connectors.iterateApps()- Python
connectors.list_apps()connectors.list_all_apps()connectors.iterate_apps()- Ruby
connectors.list_appsconnectors.list_all_appsconnectors.iterate_apps- PHP
connectors->listAppsconnectors->listAllAppsconnectors->iterateApps- Go
Connectors.ListAppsConnectors.ListAllAppsConnectors.IterateApps- Java
connectors().listAppsconnectors().listAllAppsconnectors().iterateApps- C#
Connectors.ListAppsAsyncConnectors.ListAllAppsAsyncConnectors.IterateAppsAsync- CLI
openemail connectors list-apps- MCP
listConnectorApps
GET/connector-apps/{slug}
Read an app of the catalogue
One app of the catalogue by its slug.
Requires the connectors:read scope.
Path parameters
slugstringRequiredThe slug of the app, such as
slack.
Returns
The app.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
GET/connector-categories
List app categories
The categories the catalogue sorts its apps into. Pass a slug from here as category when listing apps.
Requires the connectors:read scope.
Returns
The categories.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
GET/connectors
List connectors
The connectors the caller can reach: the ones shared with the workspace, and its own. A connector that belongs to one person is reached only by an app that person connected, which also has to hold account:read, or account:write to change it. An API key acts for the workspace and reaches the shared connectors only. A key or an app limited to particular addresses or domains does not reach the shared ones.
Requires the connectors:read scope.
Query parameters
scopestringaccountlists only the connectors that belong to the person the caller acts for,workspaceonly the shared ones.One of"account""workspace"statusstringOnly the connectors in this state.
One of"pending""active""expired""paused"appstringOnly the connectors of this app, by its slug.
Returns
The connectors, by app.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
POST/connectors
Connect an app
Starts connecting an app and returns the connector with a connectUrl. A person has to open that link and sign in to the app there, or enter its key, on a page outside this API, so the secret never passes through the caller. Read the connector again afterwards: it is active once they have finished. With no scope the connector is shared with the workspace. A connector that belongs to one person is reached only by an app that person connected, which also has to hold account:read, or account:write to change it. An API key acts for the workspace and reaches the shared connectors only. A key or an app limited to particular addresses or domains does not reach the shared ones. A plan holds 2, 10 or 50 connectors for an account and as many again for a workspace. The largest plan sets no limit of its own, and nothing holds more than 200.
Requires the connectors:write scope.
Request body
appstringRequiredThe app to connect, by the slug the catalogue lists it under, such as
slackornotion.1 to 80 charactersPattern^[a-z0-9][a-z0-9_-]*$scopestringWho the connector is for.
accountkeeps it to one person.workspaceshares it with the workspace, where tasks and anyone allowed to use connectors can reach it. Left out, it isworkspace.One of"account""workspace"labelstringA name of your own for the connector, such as Sales Slack. Up to 80 characters.
Up to 80 charactersaccessstringWhat the assistant may do through it.
readlets it look things up.fullalso lets it make changes, which it asks a person about first in chat and in tasks. Left out, it isfull.One of"read""full"
Returns
The connector, still pending, with its link.
Errors
- 403
insufficient_scope: the key or app may not connect an app for that scope.connector_limit_reached: the plan holds no more connectors.- 404
connector_app_not_found: the catalogue has no app with that slug.- 422
invalid_parameter: a field is missing or malformed.connector_app_unavailable: the app cannot be connected yet.
The errors every operation can return400401500Error catalog
Also available in
GET/connectors/{id}
Read a connector
One connector by its id, read fresh. While it is pending this also checks whether the sign-in was finished, so it is the call to make after sending somebody to connectUrl.
Requires the connectors:read scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.
Returns
The connector.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
- TypeScript
connectors.get()- Python
connectors.get()- Ruby
connectors.get- PHP
connectors->get- Go
Connectors.Get- Java
connectors().get- C#
Connectors.GetAsync- CLI
openemail connectors get- MCP
getConnector
PATCH/connectors/{id}
Update a connector
Renames a connector, pauses or resumes it, or changes its access. Send only what changes. A paused connector refuses every action until it is resumed.
Requires the connectors:write scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.
Request body
labelstringA name of your own for the connector, such as Sales Slack. Up to 80 characters.
Can be nullUp to 80 charactersaccessstringWhat the assistant may do through it.
readlets it look things up.fullalso lets it make changes, which it asks a person about first in chat and in tasks. Left out, it isfull.One of"read""full"pausedbooleantruestops every use of the connector until it is resumed.falseresumes it.
Returns
The connector after the change.
Errors
- 403
insufficient_scope: the key or app may not change this connector.connector_limit_reached: resuming it would go over what the plan holds.- 409
connector_not_active: only an active connector can be paused.- 422
invalid_parameter: nothing to change was sent, or a field is malformed.
The errors every operation can return400401404500Error catalog
Also available in
DELETE/connectors/{id}
Disconnect an app
Disconnects the app for good. The access it held in the outside app is given up there too, and its record of calls goes with it. A task that named the connector can no longer reach the app.
Requires the connectors:write scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.
Returns
Disconnected.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
POST/connectors/{id}/reconnect
Reconnect a connector
Returns a fresh connectUrl for a connector that is expired, or whose first link ran out. A person has to open that link and sign in to the app there, or enter its key, on a page outside this API, so the secret never passes through the caller. Read the connector again afterwards: it is active once they have finished. The connector keeps its id, label and access.
Requires the connectors:write scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.
Returns
The connector with a fresh link.
Errors
- 422
connector_app_unavailable: the app can no longer be connected.
The errors every operation can return400401403404500Error catalog
Also available in
GET/connectors/{id}/actions
List what a connector can do
The actions of the app behind a connector that match search, or its most used ones when search is left out. A connector set to read lists only the actions that read.
Requires the connectors:use scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.
Query parameters
searchstringWords to look for in the name or the description.
limitintegerHow many actions to return.
At least 1At most 30Default12
Returns
The matching actions.
Errors
- 409
connector_not_active: the connector is paused, pending or expired.- 503
connector_provider_failed: the connection service did not answer.
The errors every operation can return400401403404422500Error catalog
Also available in
GET/connectors/{id}/actions/{action}
Read an action
One action with the input it takes, as a JSON Schema. Build the input of a run from it.
Requires the connectors:use scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.actionstringRequiredThe action, such as
SLACK_SEND_MESSAGE, as the actions list of the connector names it.
Returns
The action with its input schema.
Errors
- 409
connector_not_active: the connector is paused, pending or expired.- 503
connector_provider_failed: the connection service did not answer.
The errors every operation can return400401403404422500Error catalog
Also available in
POST/connectors/{id}/actions/{action}/run
Run an action
Runs one action in the connected app and returns what the app answered. An action that reads runs at once, and so does one that changes something: over the API nobody is asked first, so the caller decides. Inside the app the assistant asks a person before every change. A change made in the outside app cannot be taken back from here, and the call is not repeated when it fails. Every run is listed under GET /connector-calls, without its input or its result.
Requires the connectors:use scope.
Path parameters
idstringRequiredThe connector, such as
cnr_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connectorslists it.actionstringRequiredThe action, such as
SLACK_SEND_MESSAGE, as the actions list of the connector names it.
Request body
inputRecord<string, any>The input of the action as an object, shaped as the input schema of that action describes.
Returns
The outcome. ok is false when the app itself refused the action.
Errors
- 403
connector_read_only: the connector is set toreadand the action changes something.- 409
connector_not_active: the connector is paused, pending or expired.- 422
invalid_parameter:inputis not an object or is too large.connector_action_failed: the app refused the request as it was sent.- 503
connector_provider_failed: the connection service did not answer.
The errors every operation can return400401404500Error catalog
Also available in
GET/connector-calls
List what was done through connectors
Every action that ran through a connector the caller can reach, newest first: the app, the action, whether it read or changed something, whether it worked, and whether it came from chat, a task, the API or an agent. Inputs and results are never kept. Calls are kept 90 days.
Requires the connectors:read scope.
Query parameters
connectorIdstringOnly the calls made through this connector.
scopestringaccountlists only the connectors that belong to the person the caller acts for,workspaceonly the shared ones.One of"account""workspace"limitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
A page of calls.
Errors
The errors every operation can return400401403404422500Error catalog
Also available in
- TypeScript
connectors.listCalls()connectors.listAllCalls()connectors.iterateCalls()- Python
connectors.list_calls()connectors.list_all_calls()connectors.iterate_calls()- Ruby
connectors.list_callsconnectors.list_all_callsconnectors.iterate_calls- PHP
connectors->listCallsconnectors->listAllCallsconnectors->iterateCalls- Go
Connectors.ListCallsConnectors.ListAllCallsConnectors.IterateCalls- Java
connectors().listCallsconnectors().listAllCallsconnectors().iterateCalls- C#
Connectors.ListCallsAsyncConnectors.ListAllCallsAsyncConnectors.IterateCallsAsync- CLI
openemail connectors list-calls- MCP
listConnectorCalls
Objects
Connectorobject
objectstringRequired- One of
"connector" idstringRequiredThe id, which starts with
cnr_.scopestringRequiredaccountwhen it belongs to one person,workspacewhen it is shared with the workspace.One of"account""workspace"appstringRequiredThe slug of the connected app, such as
slack.appNamestringRequiredThe name of the app, such as Slack.
appLogostringRequiredA link to the logo of the app.
Can be nulllabelstringRequiredThe name the person gave the connector, if any.
Can be nullUp to 80 charactersstatusstringRequiredpendinguntil the sign-in behindconnectUrlis finished,activewhile it works,pausedwhile a person or the plan holds it back, andexpiredwhen the app stopped accepting the connection and it has to be reconnected.One of"pending""active""expired""paused"failurestringRequiredWhy an
expiredconnector stopped working:expiredwhen the sign-in ran out,revokedwhen the access was taken away in the app,failedwhen the app refused the connection,disabledwhen the connection was switched off.Can be nullOne of"expired""revoked""failed""disabled"pausedReasonstringRequireduserwhen a person paused it,planwhen the workspace moved to a plan that holds fewer connectors.Can be nullOne of"user""plan"accessstringRequiredreadwhen the assistant may only look things up through it,fullwhen it may also make changes.One of"read""full"connectedAtstringRequiredWhen the sign-in was last finished.
Can be nullFormatdate-timelastUsedAtstringRequiredWhen an action last ran through it.
Can be nullFormatdate-timecreatedAtstringRequiredWhen the connector was created.
Formatdate-timeupdatedAtstringRequiredWhen it last changed.
Formatdate-time
ConnectorActionobject
objectstringRequired- One of
"connector_action" actionstringRequiredThe name to run the action by.
namestringRequiredWhat the action is called.
descriptionstringRequiredWhat it does.
kindstringRequiredreadwhen it only looks something up,changewhen it creates, updates, sends or deletes something, or when the app does not say.One of"read""change"
ConnectorActionDetailobject
objectstringRequired- One of
"connector_action" actionstringRequiredThe name to run the action by.
namestringRequiredWhat the action is called.
descriptionstringRequiredWhat it does.
kindstringRequiredreadwhen it only looks something up,changewhen it creates, updates, sends or deletes something, or when the app does not say.One of"read""change"inputobjectRequiredThe input the action takes, as a JSON Schema.
ConnectorActionListobject
objectstring- One of
"list"
ConnectorAppobject
objectstringRequired- One of
"connector_app" slugstringRequiredThe slug to connect the app by.
namestringRequiredWhat the app is called.
descriptionstringRequiredWhat the app is, in a sentence or two.
logostringRequiredA link to its logo.
Can be nullwebsitestringRequiredThe site of the app.
Can be nullcategoriesConnectorCategory[]RequiredactionsintegerRequiredHow many actions the app offers.
authstringRequiredsign-inwhen the person signs in to the app,keywhen they paste a key from it, and null when it cannot be connected yet.Can be nullOne of"sign-in""key"connectablebooleanRequiredWhether it can be connected today.
ConnectorAppListobject
objectstring- One of
"list" dataConnectorApp[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
ConnectorCallobject
objectstringRequired- One of
"connector_call" idstringRequiredThe id, which starts with
cnc_.connectorIdstringRequiredThe connector the call went through.
appstringRequiredThe slug of the app.
appNamestringRequiredThe name of the app.
actionstringRequiredThe action that was run.
kindstringRequiredWhether the action reads or changes something.
One of"read""change"statusstringRequiredokwhen it ran,failedwhen the app or the connection refused it,refusedwhen a rule here stopped it before it reached the app.One of"ok""failed""refused"errorCodestringRequiredThe error code of a call that did not run, such as
connector_action_failed.Can be nullsourcestringRequiredWhere the call came from:
chatfor the assistant in the app,taskfor a task running by itself,apifor this API andmcpfor an agent on the MCP server.One of"chat""task""api""mcp"durationMsintegerRequiredHow long the call took, in milliseconds.
atstringRequiredWhen it ran.
Formatdate-time
ConnectorCallListobject
objectstring- One of
"list" dataConnectorCall[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
ConnectorCategoryobject
slugstringRequiredThe value to pass as
category.namestringRequiredWhat the category is called.
ConnectorCategoryListobject
objectstring- One of
"list"
ConnectorListobject
objectstring- One of
"list" dataConnector[]
ConnectorRunobject
objectstringRequired- One of
"connector_run" connectorIdstringRequiredThe connector the action ran through.
appstringRequiredThe slug of the app.
actionstringRequiredThe action that ran.
kindstringRequiredWhether the action reads or changes something.
One of"read""change"okbooleanRequiredWhether the app carried the action out.
dataanyRequiredWhat the app answered, in its own shape. When
truncatedis true it is the start of that answer as text.errorstringRequiredWhat the app said when
okis false.Can be nulltruncatedbooleanRequiredWhether the answer was too long to return whole.
ConnectorWithLinkobject
objectstringRequired- One of
"connector" idstringRequiredThe id, which starts with
cnr_.scopestringRequiredaccountwhen it belongs to one person,workspacewhen it is shared with the workspace.One of"account""workspace"appstringRequiredThe slug of the connected app, such as
slack.appNamestringRequiredThe name of the app, such as Slack.
appLogostringRequiredA link to the logo of the app.
Can be nulllabelstringRequiredThe name the person gave the connector, if any.
Can be nullUp to 80 charactersstatusstringRequiredpendinguntil the sign-in behindconnectUrlis finished,activewhile it works,pausedwhile a person or the plan holds it back, andexpiredwhen the app stopped accepting the connection and it has to be reconnected.One of"pending""active""expired""paused"failurestringRequiredWhy an
expiredconnector stopped working:expiredwhen the sign-in ran out,revokedwhen the access was taken away in the app,failedwhen the app refused the connection,disabledwhen the connection was switched off.Can be nullOne of"expired""revoked""failed""disabled"pausedReasonstringRequireduserwhen a person paused it,planwhen the workspace moved to a plan that holds fewer connectors.Can be nullOne of"user""plan"accessstringRequiredreadwhen the assistant may only look things up through it,fullwhen it may also make changes.One of"read""full"connectedAtstringRequiredWhen the sign-in was last finished.
Can be nullFormatdate-timelastUsedAtstringRequiredWhen an action last ran through it.
Can be nullFormatdate-timecreatedAtstringRequiredWhen the connector was created.
Formatdate-timeupdatedAtstringRequiredWhen it last changed.
Formatdate-timeconnectUrlstringRequiredThe page a person has to open to sign in to the app, or to enter its key. It is shown once, here.
FormaturiconnectExpiresAtstringRequiredWhen the link stops working.
Formatdate-time
DeletedConnectorobject
objectstringRequired- One of
"connector" idstringRequiredThe id of the connector that was disconnected.
scopestringRequiredWhether it belonged to one person or to the workspace.
One of"account""workspace"appstringRequiredThe slug of the app it connected.
deletedbooleanRequired- One of
true