# client.connection_choices

> client.connection_choices — the connectionChoices operations.

`client.connection_choices` — the `connectionChoices` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.connection_choices.list()`

```python signature
list(
    *,
    project_id: str | UUID,
    agent_id: str | UUID | None = None,
    flow_id: str | UUID | None = None,
    app: str | None = None,
    tool_id: str | UUID | None = None,
    owner: Literal['me'] | None = None,
    include_removed: bool | None = None,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ConnectionChoicePage
```

List connection choices. `GET /v1/connection-choices`

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.

## `client.connection_choices.set()`

```python signature
set(
    body: SetConnectionChoiceBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ConnectionChoice
```

Choose a connection. `PUT /v1/connection-choices`

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.

## `client.connection_choices.remove()`

```python signature
remove(
    choice_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ConnectionChoiceDeleteResult
```

Remove a connection choice. `DELETE /v1/connection-choices/{choiceId}`

Removes a live choice. It's kept, with `removedAt` and `removedBy`: `GET /v1/connection-choices?includeRemoved=true` lists it. A company choice: the admins of its project only (`admin` on the project). A person's: that person alone; to anyone else it's not found.

## `client.connection_choices.candidates()`

```python signature
candidates(
    *,
    project_id: str | UUID,
    app: str | None = None,
    owner: Literal['me'] | None = None,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ConnectionCandidatePage
```

List connection candidates. `GET /v1/connection-choices/candidates`

The connections a choice in the project may name: live ones, working or needing a reconnect, in this server's environment, on a live registration that allows the project. The company's: the project's admins read each in full, and its members read `connectionId` and `name` only (`read` on the project). With `owner=me`, the caller's own instead, in full, with `main`.

## `client.connection_choices.needs()`

```python signature
needs(
    *,
    project_id: str | UUID,
    agent_id: str | UUID | None = None,
    flow_id: str | UUID | None = None,
    app: str | None = None,
    timeout: float | None = None,
) -> ConnectionChoiceNeeds
```

List what a choice may be for. `GET /v1/connection-choices/needs`

Each of an agent's or flow's tools' connections, at the version it resolves now: the tool, its name for the connection (`need`), the app and whose (`as`), and whether a choice for it may be a set (`set.allowed`, else `set.reason`: `changes`, `sensitive-data-egress` or `accounts-input`). A tool whose version couldn't be read is listed in `unread`. The project's members (`read` on the project).