Connections

All paths below are relative to the base URL https://api.agentdepot.org — for example GET https://api.agentdepot.org/api/orgs/{org_id}/connections. Authenticate with an Authorization: Bearer <token> header. See the REST API reference for details.

GET /api/orgs/{org_id}/connections

List Connections

List connections for the organisation, visible to the caller.

PRIVATE connections owned by someone else are omitted entirely (not just redacted). wildcard_agent_count is the number of org agents with a "*" tool grant — excluded from every connection’s used_by_agent_ids.

Omit limit to get every connection; total is a real COUNT of the visible set either way — never the size of the page.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/connections/{connection_id}

Get Connection

Get a single connection by its prefixed ID.

A PRIVATE connection owned by someone else 404s — indistinguishable from a connection that doesn’t exist.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionResponse
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/connections/{connection_id}

Update Connection

Update a connection’s status, display label and/or decision policy.

Any org member may manage connections for now — see issue #260. A PRIVATE connection owned by someone else 404s.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
decision_mode	string	no
label	string	no
status	string	no

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/connections/{connection_id}

Delete Connection

Disconnect / remove a connection.

Any org member may remove a connection visible to them for now — see issue #260. A PRIVATE connection owned by someone else 404s.

Deleting a connection that agents depend on returns 409 with the dependent agent ids; re-issue with ?acknowledge_dependents=true to proceed — the same shape PATCH /{connection_id}/scope uses for privatizing. Deletion is never refused outright, only never silent: removing the row takes the connection away from every agent, including the owner’s own.

Parameters

Name	In	Type	Required	Description
acknowledge_dependents	query	boolean	no
connection_id	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/connections/{connection_id}/owner

Assign Connection Owner

Hand a connection to a different member. Admin/owner or current owner.

Ownership decides who a private connection is visible to and which agents reach it (run_as=owner), so this moves real capability — but it does not re-authenticate. The stored credential still belongs to whoever authorized it; moving the underlying account to a different person means reconnecting.

Parameters

Name	In	Type	Required	Description
connection_id	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
owner_user_id	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionResponse
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/connections/{connection_id}/scope

Update Connection Scope

Convert a connection’s visibility scope (private ⇄ org).

A private row is only visible to its owner, so only the owner can re-scope it. A shared (org) row is visible to everyone, but visibility is not permission: re-scoping one requires an org admin/owner or the connection’s own owner — taking a shared credential away from the whole org is not a change any member should be able to make.

Privatizing a connection that agents depend on returns 409 with the dependent agent ids; re-issue with acknowledge_dependents: true to proceed. Making an ownerless row private records the actor as its owner (a private row with no owner would be visible to nobody).

Parameters

Name	In	Type	Required	Description
connection_id	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
acknowledge_dependents	boolean	no
scope	string	yes

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/connections/by-slug/{slug}

Get Connection By Slug

Get a single connection by its URL slug.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
slug	path	string	yes

Responses

Status	Description	Body
200	Successful Response	agentdepot_api__routers__connections__ConnectionResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/connections/catalog

Get Catalog

Return the app-level connections catalog: one card per product.

Merges the static apps (:func:iter_static_apps) with dynamic Composio apps (every ENABLED auth-config toolkit not already covered by a static app’s Composio method, e.g. Freshdesk) and a synthetic “Custom MCP” entry. connected reflects whether the org has a connection (visible to the caller) whose provider_key matches the app.

app_key is unique across the returned items: a toolkit whose slug equals a static app’s key is folded into that app as an extra connect method (:func:with_composio_method), never emitted as a second card.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	CatalogResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/connections/catalog/{app_key}/methods

Get Catalog App Methods

Return the ranked connect methods for one catalog app.

app_key is either a static app key (:data:APP_MAP), the synthetic "mcp_server" key, or an ENABLED Composio toolkit slug not covered by a static app.

A static app whose key is also an ENABLED Composio toolkit gets that managed method appended (mirroring the catalog’s fold — see :func:with_composio_method). Without it this branch returned only the native params form and the managed route was unreachable, even though the catalog advertised it.

Parameters

Name	In	Type	Required	Description
app_key	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	MethodListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/connections/stewardship

List Connections For Stewardship

Every connection in the org, including private ones. Admin/owner only.

Exists so an outage is diagnosable and an offboarding is answerable: a connection owned by someone who has left breaks the agents that depend on it, and with per-user visibility alone nobody else can see the row to work out why.

Seeing is not using. No credentials are returned, and the tool gateway never consults this route — an admin can see a member’s private connection here and still cannot point an agent at it. Ordinary listing (GET /connections) is unchanged and stays per-viewer.

Declared before /{connection_id} so the literal path wins over the parameterised one.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	StewardshipListResponse
422	Validation Error	HTTPValidationError