Choose a connection
const url = 'https://example.com/v1/connection-choices';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","agentId":"example","flowId":"example","toolId":"example","need":"example","connectionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","connectionIds":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"person":{"userId":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/v1/connection-choices \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agentId": "example", "flowId": "example", "toolId": "example", "need": "example", "connectionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "connectionIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "person": { "userId": "example" } }'Chooses which connection an agent or a flow uses, in the project and this server’s environment, for the connection’s app; with toolId, which one that tool uses, ahead of the agent’s or flow’s. A tool’s choice may be a set (connectionIds): a call of a tool that changes nothing names one of them, by name, else uses connectionId. A company choice is the project’s admins’ (admin on the project). A person’s (person) is that person’s alone, for their own runs, and needs only what running the agent or flow does. The connection must be a candidate (GET /v1/connection-choices/candidates, with owner=me for your own). Choosing the connection already chosen answers that choice as it is. Choosing another removes that choice and makes a new one at the next version, in one step.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”Name what the choice is for: agentId or flowId, one of them, and toolId for a tool’s own. A company choice is a project admin’s; a person’s (person) is theirs alone.
object
One of the project’s agents.
One of the project’s flows.
One of the agent’s or flow’s tools that uses the connection’s app.
The tool’s name for the connection. It may be left out when the tool uses the app once.
One of the candidates (GET /v1/connection-choices/candidates, with owner=me for a person’s own). The choice is for its app. With connectionIds, the set’s default.
A set, for a tool’s choice: 2 to 10 different candidates, connectionId among them, each named. Only for a tool that changes nothing, doesn’t declare sensitive-data-egress and has no accounts input of its own (GET /v1/connection-choices/needs).
A choice of your own connection, for your own runs: you.
object
Examplegenerated
{ "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "agentId": "example", "flowId": "example", "toolId": "example", "need": "example", "connectionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "connectionIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "person": { "userId": "example" }}Responses
Section titled “Responses”The choice.
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
{ "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"}A malformed body or unknown field; a projectId or connectionId that is not a UUID; both agentId and flowId, or neither; a person’s own connection in a company choice; a person who isn’t the caller; a toolId the agent or flow has no tool of the app by; a need that’s missing for a tool that uses the app twice, or one the tool doesn’t have; or a set that isn’t for one tool, isn’t 2 to 10 different connections with the default among them, is for a tool that changes things, may send what it reads elsewhere (sensitive-data-egress) or has its own accounts input, or has a member with no name (bad-input, details.field).
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" }}A company choice by a caller who isn’t an admin of the project, or a person’s by one who may not run its agent or flow (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" }}No such project (project-not-found); the agent or flow isn’t one of the project’s (agent-not-found, flow-not-found); or a connection isn’t a candidate, the same answer as for one that doesn’t exist (connection-not-found, details.field connectionId or connectionIds).
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" }}Idempotency-Key was reused with a different body, or resource-state conflict.
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 request body is over the API’s limit (request-too-large; details.maxBytes says how much).
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" }}Server error (unmapped domain code or framework crash).
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 choice couldn’t be stored just now (connection-store-failed), or the Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable, with Retry-After).
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" }}See also
GET /v1/connection-choices: List connection choices- Choose a connection
- Kindgi 0.5.0
- Error code
agent-not-found - Error code
bad-input - Error code
connection-not-found - Error code
connection-store-failed - Error code
flow-not-found - Error code
idempotency-store-unavailable - Error code
permission-denied - Error code
project-not-found - Error code
request-too-large - Every error code