List connection choices
const url = 'https://example.com/v1/connection-choices?projectId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&owner=me&includeRemoved=false&limit=25';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/connection-choices?projectId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&owner=me&includeRemoved=false&limit=25' \ --header 'Authorization: Bearer <token>'The project’s live choices in this server’s environment: which connection each agent or flow, or one of its tools, uses for an app. The project’s members may read them (read on the project): the company’s, and their own. A tenant admin reads every person’s too; with owner=me, anyone reads their own alone. Removed choices, a choice’s history, are listed only with includeRemoved=true. A choice of a connection that’s since been disconnected stays listed until it’s set again or removed.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The project.
Only this agent’s.
Only this flow’s.
Only this app’s (its entry id).
Only this tool’s own choices.
me: only the caller’s own, even for a tenant admin.
true lists removed choices too.
1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Responses
Section titled “Responses”Page of choices.
object
Which connection an agent or a flow uses for an app in a project, in one env: agentId or flowId, one of them. The company’s, or a person’s own (person), for their runs. With toolId, it’s that tool’s, which comes before the agent’s or flow’s. A choice is never changed: changing it removes it and makes a new one at the next version.
object
The app’s entry id (google): the connection’s.
The tool it’s for, with need. Absent: the agent’s or flow’s choice, for every tool’s need of the app.
The tool’s name for the connection (calendar), with toolId.
The chosen connection, and a set’s default. A choice of a connection that’s since been disconnected stays until it’s set again or removed.
A set: the connections a call of the tool may name one of (by its name), connectionId among them. A call that names none uses connectionId. Only a tool’s choice, for a tool that changes nothing. Absent for one connection.
Whose choice it is, for a person’s connection: theirs alone to make, change or remove. Absent: the company’s.
object
From 1, per project, env, agent or flow, app, tool and need, and person.
When it was removed, or replaced by a new choice. Only a removed choice has it.
Examplegenerated
{ "data": [ { "choiceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "envName": "example", "agentId": "example", "flowId": "example", "app": "example", "toolId": "example", "need": "example", "connectionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "connectionIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "person": { "userId": "example" }, "version": 1, "createdAt": "2026-04-15T12:00:00Z", "createdBy": "example", "removedAt": "2026-04-15T12:00:00Z", "removedBy": "example" } ], "nextCursor": "example", "hasMore": true}No projectId, or one that is not a UUID; an app that is not an entry id; both agentId and flowId; an owner other than me; or an includeRemoved other than true or false (bad-input).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Not a member of the project (permission-denied).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}