Connections

Reference article: Part of the API reference. To connect and manage apps in Nimbus, see Managing connections.

A connection is an app linked to Nimbus, such as Slack or Google Calendar, that the agent and runs can use. These endpoints list your organization's connections and whether each one works, so you can monitor integrations from your own dashboards and catch a broken one before work depends on it.

Connections are read-only through the API. They only ever include safe fields: which app it is, its status, and who owns it. Credentials, tokens, and secrets are never returned.

The Connection object

{
  "id": "f2b7d4e9-8a1c-4c5f-b3e6-9d0a7c2e5f18",
  "object": "connection",
  "app": "google_calendar",
  "status": "connected",
  "owner": "user",
  "workstream": null,
  "created": 1755100800,
  "updated": 1758700000
}

Field	Type	Description
`id`	string	The connection's ID.
`object`	string	Always `connection`.
`app`	string	The connected app, such as `google_calendar` or `slack`.
`status`	string	`pending_oauth`, `connected`, `revoked`, or `error`. See Statuses.
`owner`	string	`user` if one person connected it for themselves, `organization` if it's shared by the organization.
`workstream`	string or null	The ID of the workstream it's tied to, if any.
`created`	integer or null	When it was connected, in Unix seconds.
`updated`	integer or null	When it last changed, in Unix seconds.

Statuses {#statuses}

Status	Meaning
`pending_oauth`	Someone started connecting the app but hasn't finished signing in to it.
`connected`	The connection works.
`error`	The connection has a problem. Check it in the app, and reconnect it if needed.
`revoked`	The connection was disconnected. Hidden from lists unless you filter for it.

List connections

Returns the organization's connections, newest first, including ones individual people connected for themselves. Revoked connections are left out unless you filter for them with status=revoked.

GET /v1/connections

Scope: connections:read

Parameter	In	Type	Description
`limit`	query	integer, optional	How many objects to return, 1–100. Default `20`.
`cursor`	query	string, optional	The `next_cursor` from the previous page. See Pagination.
`status`	query	string, optional	Only connections with this status: `pending_oauth`, `connected`, `revoked`, or `error`.

::: code-group

curl "https://api.gonimbus.ai/v1/connections?status=error" \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch('https://api.gonimbus.ai/v1/connections?status=error', {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const { data: broken } = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/connections",
    params={"status": "error"},
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
broken = response.json()["data"]

:::

Returns a list object of Connection objects.

Retrieve a connection

Returns one connection, including a revoked one.

GET /v1/connections/{connection}

Scope: connections:read

Parameter	In	Type	Description
`connection`	path	string	The connection's ID.

::: code-group

curl https://api.gonimbus.ai/v1/connections/f2b7d4e9-8a1c-4c5f-b3e6-9d0a7c2e5f18 \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch('https://api.gonimbus.ai/v1/connections/f2b7d4e9-8a1c-4c5f-b3e6-9d0a7c2e5f18', {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const connection = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/connections/f2b7d4e9-8a1c-4c5f-b3e6-9d0a7c2e5f18",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
connection = response.json()

:::

Returns the Connection object, or 404 resource_missing if no connection has that ID.

Example scenario

An IT team runs a nightly check that lists connections with status=error and posts any it finds to their operations workstream with Post a message, naming the app and whether it's a personal or organization connection. Someone reconnects it in the morning, before a scheduled run fails for lack of access.

FAQ

Can I get a connection's access token through the API?

No. The API never returns credentials, tokens, or references to them, for any key type.

Can I connect or disconnect an app through the API?

No. Connect, reconnect, and remove apps in the app. See Managing connections.

Why is a connection I disconnected not in the list?

Disconnected connections have the status revoked and are hidden by default. List them with status=revoked.

Do I see people's personal connections?

Yes, with owner set to user, so you can tell they're personal. You see which app is connected and its status, never its credentials.

How do I fix a connection in error?

Check it in the app, where the connector card shows what went wrong, and reconnect it. See Managing connections.