> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Cosmos DB integration

[Back to list of integrations](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems.md)

Use the Azure Cosmos DB integration for NoSQL to query databases and create, read, update, patch, or delete items through Action Tools.

| Authentication | Actions |
| - | - |
| Cosmos DB account key or resource token | ([9](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems/azure-cosmos-db#supported-actions)) |

## Supported actions

| Action | Use it to |
| - | - |
| [List Databases](#list-databases) | List database IDs. |
| [List Containers](#list-containers) | List container IDs in a database. |
| [Query Items](#query-items) | Run a SQL query against a container. |
| [Read Item](#read-item) | Read an item by ID and partition key. |
| [Create Item](#create-item) | Create an item. |
| [Upsert Item](#upsert-item) | Create or replace an item. |
| [Replace Item](#replace-item) | Replace an item by ID and partition key. |
| [Patch Item](#patch-item) | Apply patch operations to an item. |
| [Delete Item](#delete-item) | Delete an item by ID and partition key. |

## Prerequisites

* An Azure Cosmos DB for NoSQL account and its endpoint.
* An account key or resource token with access to the databases, containers, and operations used by the tools.

## Set up the integration

**1. Prepare the Cosmos DB connection**

Have the account endpoint and account key or resource token ready. If you want actions to use profile defaults, also identify the database, container, and partition key.

**2. Create the auth profile**

In **Integrations**, select **Azure Cosmos DB** > **Connect**. On **Project Auth Profiles**, select **New Profile** > **Integration Profile** > **Azure Cosmos DB** > **Continue**. Configure the endpoint and key. Select **Account Key** or **Resource Token** for the token type; **Account Key** is the default. You can also set default database, container, and partition key values. For a resource token, you can optionally enter its expiry as an ISO timestamp for operator visibility. Select **Create Profile**.

**3. Create the action tool**

In **Tools**, select **New Tool** > **Action** > **Azure Cosmos DB** > **Continue**. Select the action and auth profile, configure its inputs, and select **Create Tool**. Then [assign the tool to an agent](https://koreai.mintlify.site/agent-platform/tools/actions.md#assign-an-action-to-an-agent).

## Action reference

Database and container action inputs are optional when you set them in the auth profile. **Read Item**, **Replace Item**, **Patch Item**, and **Delete Item** also need a partition key from the action or profile. **Create Item** and **Upsert Item** use the partition-key field in the item.

> [accordion] List Databases
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `limit` | number | No | Maximum databases to return per page (`1`–`500`). Defaults to `100`. |
> | `continuationToken` | string | No | Token from the previous result to fetch the next page. |

> [accordion] List Containers
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to list containers from. Uses the profile default if omitted. |
> | `limit` | number | No | Maximum containers to return per page (`1`–`500`). Defaults to `100`. |
> | `continuationToken` | string | No | Token from the previous result to fetch the next page. |

> [accordion] Query Items
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to query. Uses the profile default if omitted. |
> | `container` | string | No | Container to query. Uses the profile default if omitted. |
> | `query` | string | Yes | Cosmos DB SQL query, for example `SELECT * FROM c WHERE c.status = @status`. |
> | `parameters` | JSON | No | Query parameters as an array of `{ "name": "@param", "value": ... }` objects. Defaults to `[]`. |
> | `maxItemCount` | number | No | Maximum items to return per page (`1`–`500`). Defaults to `100`. |
> | `continuationToken` | string | No | Token from a previous result to fetch the next page. |

> [accordion] Read Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database containing the item. Uses the profile default if omitted. |
> | `container` | string | No | Container containing the item. Uses the profile default if omitted. |
> | `id` | string | Yes | Item ID. |
> | `partitionKey` | string | No | Partition key for the item. Uses the profile default if omitted. |

> [accordion] Create Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to create the item in. Uses the profile default if omitted. |
> | `container` | string | No | Container to create the item in. Uses the profile default if omitted. |
> | `item` | JSON | Yes | Item to create, including the container partition-key field. |

> [accordion] Upsert Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database for the item. Uses the profile default if omitted. |
> | `container` | string | No | Container for the item. Uses the profile default if omitted. |
> | `item` | JSON | Yes | Item to create or replace, including the container partition-key field. |

> [accordion] Replace Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database containing the item. Uses the profile default if omitted. |
> | `container` | string | No | Container containing the item. Uses the profile default if omitted. |
> | `id` | string | Yes | Item ID. |
> | `partitionKey` | string | No | Partition key for the item. Uses the profile default if omitted. |
> | `item` | JSON | Yes | Replacement item. |

> [accordion] Patch Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database containing the item. Uses the profile default if omitted. |
> | `container` | string | No | Container containing the item. Uses the profile default if omitted. |
> | `id` | string | Yes | Item ID. |
> | `partitionKey` | string | No | Partition key for the item. Uses the profile default if omitted. |
> | `operations` | JSON | Yes | Array of Cosmos DB patch operations, such as `[{"op":"replace","path":"/status","value":"active"}]`. |

> [accordion] Delete Item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database containing the item. Uses the profile default if omitted. |
> | `container` | string | No | Container containing the item. Uses the profile default if omitted. |
> | `id` | string | Yes | Item ID. |
> | `partitionKey` | string | No | Partition key for the item. Uses the profile default if omitted. |

## Troubleshoot common issues

| Issue | Resolution |
| - | - |
| Connection fails | Verify the account endpoint, key, and token type. For a resource token, check that it is still valid. |
| A read, replace, patch, or delete reports a missing partition key | Supply it on the action or in the auth profile. Include the container partition-key field in items you create or upsert. |
| A query or patch fails | Check the Cosmos DB SQL, query parameter array, or patch operation array. |
| An action result exceeds the output limit | Reduce the number of returned items or fields. Connector responses larger than 2 MB are rejected. |

## Related articles

* [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles)
* [Action Tools](https://koreai.mintlify.site/agent-platform/tools/actions.md)
* [Azure Cosmos DB documentation](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.