> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/chroma-cloud.md).

# Chroma Cloud

Create vector collections, add and update embedded documents, query nearest records, and delete collections.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector            | Authentication |
| -------------------- | -------------- |
| Chroma Cloud API Key | API Key        |

#### Chroma Cloud API Key

Connect one Chroma Cloud database with an API key.

**Set up in Chroma Cloud**

1. Prepare the Chroma Cloud account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Copy CHROMA\_API\_KEY from the Connect panel in Chroma Cloud.
3. **Tenant ID:** Copy CHROMA\_TENANT from the database Connect panel.
4. **Database Name:** Copy CHROMA\_DATABASE from the database Connect panel.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Chroma Cloud API Key**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required                 | What to enter                                                                                                  |
| ------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes                      | Copy CHROMA\_API\_KEY from the Connect panel in Chroma Cloud. [Provider instructions](https://trychroma.com/). |
| Tenant ID     | Yes                      | Copy CHROMA\_TENANT from the database Connect panel. [Provider instructions](https://trychroma.com/).          |
| Database Name | Yes                      | Copy CHROMA\_DATABASE from the database Connect panel. [Provider instructions](https://trychroma.com/).        |
| Region        | Optional / as applicable | Select the region shown by CHROMA\_HOST in the database Connect panel.                                         |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Chroma Cloud** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Collection

Create an empty Chroma Cloud collection.

**Inputs**

| Field           | Type   | Required | Description                                       |
| --------------- | ------ | -------- | ------------------------------------------------- |
| Collection Name | string | Yes      | Unique lowercase collection name, 3 to 128 bytes. |
| Metadata JSON   | code   | No       | Optional JSON object stored on the collection.    |

**Outputs**

| Field      | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| Collection | object | Created Chroma Cloud collection. |

#### Add Documents

Add records and caller-provided embeddings to a collection.

**Inputs**

| Field           | Type            | Required | Description                                                                      |
| --------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
| Collection      | select (string) | Yes      | Collection that receives the records. Options load from the selected connection. |
| Record IDs JSON | code            | Yes      | JSON array of unique record IDs.                                                 |
| Embeddings JSON | code            | Yes      | JSON array of dense embedding vectors.                                           |
| Documents JSON  | code            | No       | Optional aligned JSON array of document text or null values.                     |
| Metadata JSON   | code            | No       | Optional aligned JSON array of metadata objects or null values.                  |
| URIs JSON       | code            | No       | Optional aligned JSON array of source URIs or null values.                       |

**Outputs**

| Field           | Type          | Description                           |
| --------------- | ------------- | ------------------------------------- |
| Collection ID   | string        | Collection that received the records. |
| Submitted Count | integer       | Number of submitted records.          |
| Record IDs      | string\_array | Submitted record IDs.                 |

#### Query Collection

Find nearest records using caller-provided query embeddings.

**Inputs**

| Field                     | Type            | Required | Description                                                      |
| ------------------------- | --------------- | -------- | ---------------------------------------------------------------- |
| Collection                | select (string) | Yes      | Collection to search. Options load from the selected connection. |
| Query Embeddings JSON     | code            | Yes      | JSON array of dense query vectors.                               |
| Results Per Query         | integer         | No       | Maximum matches returned for each query vector. Default: 10.     |
| Advanced Options          | boolean         | No       | Show filters and optional response fields. Default: false.       |
| Metadata Filter JSON      | code            | No       | Optional Chroma metadata filter JSON.                            |
| Document Filter JSON      | code            | No       | Optional Chroma document-content filter JSON.                    |
| Include URIs              | boolean         | No       | Include stored source URIs.                                      |
| Include Stored Embeddings | boolean         | No       | Include stored vectors, increasing response size and cost.       |

**Outputs**

| Field         | Type          | Description                            |
| ------------- | ------------- | -------------------------------------- |
| Query Results | object\_array | Matches grouped by input query vector. |

#### Update Documents

Update existing Chroma records by ID.

**Inputs**

| Field                       | Type            | Required | Description                                                                   |
| --------------------------- | --------------- | -------- | ----------------------------------------------------------------------------- |
| Collection                  | select (string) | Yes      | Collection containing the records. Options load from the selected connection. |
| Record IDs JSON             | code            | Yes      | JSON array of record IDs to update.                                           |
| Replacement Embeddings JSON | code            | No       | Optional aligned JSON array of replacement vectors.                           |
| Replacement Documents JSON  | code            | No       | Optional aligned JSON array of replacement text or null values.               |
| Replacement Metadata JSON   | code            | No       | Optional aligned JSON array of replacement metadata.                          |
| Replacement URIs JSON       | code            | No       | Optional aligned JSON array of replacement URIs.                              |

**Outputs**

| Field           | Type          | Description                        |
| --------------- | ------------- | ---------------------------------- |
| Collection ID   | string        | Collection containing the records. |
| Submitted Count | integer       | Number of submitted record IDs.    |
| Record IDs      | string\_array | Submitted record IDs.              |

#### Delete Collection

Permanently delete a collection after exact-name confirmation.

**Inputs**

| Field                   | Type            | Required | Description                                                                  |
| ----------------------- | --------------- | -------- | ---------------------------------------------------------------------------- |
| Collection              | select (string) | Yes      | Collection to delete permanently. Options load from the selected connection. |
| Confirm Collection Name | string          | Yes      | Enter the collection's exact name to confirm deletion.                       |

**Outputs**

| Field           | Type    | Description                 |
| --------------- | ------- | --------------------------- |
| Collection ID   | string  | Deleted collection UUID.    |
| Collection Name | string  | Deleted collection name.    |
| Deleted         | boolean | Whether deletion completed. |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/chroma-cloud.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
