canonical: https://jentic.com/apis/azure.com/azure-cosmos-db

# Microsoft Azure Cosmos DB

Jentic publishes the only available OpenAPI specification for Cosmos DB, keeping it validated and agent-ready. The Azure Cosmos DB Resource Provider REST API manages globally distributed, multi-model database accounts on Azure, including SQL (Core), MongoDB, Cassandra, Gremlin, and Table API surfaces. It exposes 100 operations across 64 paths covering database account provisioning, throughput and failover policy configuration, region replication, key rotation, and per-API resource lifecycle for keyspaces, containers, graphs, and stored procedures. Use it to programmatically create Cosmos DB accounts, regenerate access keys, and manage the underlying SQL databases, Cassandra keyspaces, MongoDB collections, Gremlin graphs, and Table resources together with their throughput settings.

## For AI agents

Provision and manage Azure Cosmos DB accounts and their SQL, MongoDB, Cassandra, Gremlin, and Table resources, including throughput, failover, and key rotation, across 100 operations on the Azure Resource Manager control plane.

## Scope

Does not handle data-plane document queries, indexing policies at runtime, or Cosmos DB SDK client connections - use for Resource Manager control-plane provisioning and management of accounts, databases, containers, keys, and throughput only.

## Capabilities

- Create and delete Cosmos DB database accounts with configured consistency levels and geo-replication regions
- List and update SQL databases, containers, stored procedures, triggers, and user-defined functions inside an account
- Manage Cassandra keyspaces and tables, MongoDB databases and collections, Gremlin databases and graphs, and Table API resources under a single account
- Regenerate primary and secondary account keys and rotate connection strings for an existing Cosmos DB account
- Configure throughput (RU/s) settings for databases and containers across all supported APIs
- Trigger manual failover by changing the write region priority on a multi-region account
- List metric definitions, metrics, and usage data for Cosmos DB accounts, databases, containers, and partition key ranges

## Use cases

### Provision a Globally Distributed Database

Create a Cosmos DB database account with geo-replication across multiple Azure regions and a chosen consistency level (strong, bounded staleness, session, consistent prefix, or eventual). The Resource Provider REST API handles the underlying provisioning, region pairing, and write region selection. A single account creation call can configure multi-region writes, automatic failover, and the API surface (SQL, MongoDB, Cassandra, Gremlin, or Table). Provisioning typically completes in 5-10 minutes and the account is ready for data plane connections.

Example prompt: Create a Cosmos DB account named 'orders-db-prod' in resource group 'rg-prod' with SQL API, session consistency, and replicas in eastus and westeurope, then return the connection string

### Rotate Database Account Access Keys

Regenerate the primary or secondary key on a Cosmos DB account as part of a scheduled credential rotation policy. The API exposes regenerate-key endpoints that issue a new key while leaving the alternate key valid, allowing applications to switch over without downtime. Pair with listKeys to retrieve the new connection string and propagate it to dependent services. This is the standard pattern for compliance-driven 90-day key rotations.

Example prompt: Regenerate the secondary key for Cosmos DB account 'orders-db-prod', wait 60 seconds, then regenerate the primary key and return the new primary connection string

### Manage Multi-Model Resources

Operate on Cassandra keyspaces and tables, MongoDB databases and collections, Gremlin graphs, SQL containers, and Table API tables through a unified Resource Manager surface. Each API surface has dedicated CRUD and throughput endpoints under the same account, so a single integration can manage all five database models. Useful for platform teams running polyglot persistence and needing one control plane for backup, throughput, and quota management.

Example prompt: List all SQL databases under Cosmos DB account 'orders-db-prod', then for each database list its containers and current throughput in RU/s

### Trigger Manual Region Failover

Force a write-region failover on a multi-region Cosmos DB account during a regional outage or DR drill. The failoverPriorityChange operation reorders the write priority list so a designated read region becomes the new write region. The control plane completes the failover within minutes and clients reconnect to the new write region. This is the agent-driven equivalent of the Azure Portal's manual failover button.

Example prompt: Initiate manual failover on Cosmos DB account 'orders-db-prod' so westeurope becomes the new write region and eastus drops to priority 1

### AI Agent Database Provisioning Workflow

An AI agent can provision and configure Cosmos DB accounts on demand through Jentic. The agent searches for the right operation by intent ('create cosmos db account'), Jentic returns the matching DatabaseAccounts_CreateOrUpdate operation with its input schema, and the agent executes the call with managed Azure credentials from your Jentic One instance. The same flow applies to key rotation, throughput updates, and metric retrieval. This removes the need for the agent to load 100 endpoint definitions or hold a service principal secret in context.

Example prompt: Search Jentic for 'provision an Azure Cosmos DB account', load the DatabaseAccounts_CreateOrUpdate schema, and execute the call to create a new account with the user-supplied parameters

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/databaseAccounts | List all Cosmos DB accounts in a subscription |
| DELETE | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName} | Delete a Cosmos DB database account |
| GET | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/cassandraKeyspaces | List Cassandra keyspaces under an account |
| GET | /providers/Microsoft.DocumentDB/operations | List available Microsoft.DocumentDB resource provider operations |

## Key resources

- **DatabaseAccounts** — Provision, list, update, delete Cosmos DB accounts and manage failover priority and keys
- **SqlResources** — Manage SQL databases, containers, stored procedures, triggers, and user-defined functions
- **MongoDBResources** — Manage MongoDB databases and collections under a Cosmos DB account
- **CassandraResources** — Manage Cassandra keyspaces and tables and their throughput settings
- **GremlinResources** — Manage Gremlin databases and graphs and their throughput
- **TableResources** — Manage Table API tables and their throughput

## Why Jentic

- **Setup:** Wiring the Cosmos DB Resource Provider by hand means an Azure AD app registration for the OAuth implicit flow against management.azure.com, MSAL token handling, and polling the Azure-AsyncOperation header for long-running account creation yourself. Through Jentic you install once, import Cosmos DB from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** The subscription, resource group, and account name are all URL path parameters (/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}), so a rule can pin the agent to one Cosmos DB account. You choose the operations it may call, so destructive ones like deleting an account or regenerating its keys are not included unless you add them.
- **Credential handling:** Your Azure service principal credentials are stored once, encrypted, by your own Jentic One instance and injected as a scoped Resource Manager bearer token at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'provision an Azure Cosmos DB account' or 'rotate a Cosmos DB key', and Jentic returns the matching Resource Manager operation such as DatabaseAccounts_CreateOrUpdate with its input schema so the agent calls the right endpoint without loading all 100 operations.

## Related APIs

- **Azure SQL Management** — Manage Azure SQL Database servers and databases instead of Cosmos DB's multi-model NoSQL accounts.
- **Data Lake Store Account Management** — Provision Data Lake Store accounts for analytics workloads alongside Cosmos DB transactional storage.
- **Azure Monitor Management** — Configure metric alerts and diagnostic settings for the Cosmos DB accounts you provision.
- **Key Vault Management** — Store rotated Cosmos DB connection strings as Key Vault secrets for downstream services.

## FAQ

### Why is there no official OpenAPI spec for Cosmos DB?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Cosmos DB via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Cosmos DB management API use?

The Resource Provider API uses Azure Active Directory OAuth 2.0 with the user_impersonation scope against the Azure Resource Manager (https://management.azure.com/). Jentic stores the service principal credentials in its encrypted vault and issues scoped bearer tokens to agents at execution time, so raw client secrets never enter the agent context.

### Can I provision a multi-region Cosmos DB account with this API?

Yes. The DatabaseAccounts create-or-update endpoint accepts a locations array that defines write and read regions plus failover priorities. Setting enableMultipleWriteLocations=true configures multi-master writes. Provisioning completes in 5-10 minutes.

### What are the rate limits for the Cosmos DB management API?

The Azure Resource Manager applies subscription-level throttling (typically 1,200 read and 1,200 write requests per hour per subscription, with burst allowances). Long-running operations such as account creation return 202 Accepted with an Azure-AsyncOperation header that you poll for completion.

### How do I rotate a Cosmos DB account key through Jentic?

Run pip install jentic, then search Jentic for 'regenerate cosmos db key'. Load the DatabaseAccounts_RegenerateKey schema and execute it with the resourceGroupName, accountName, and keyKind ('primary', 'secondary', 'primaryReadonly', or 'secondaryReadonly'). Pair with DatabaseAccounts_ListKeys to retrieve the new connection string.

### Does this API let me run queries or write data to Cosmos DB?

No. This is the management/control plane only - it provisions accounts, databases, containers, throughput, and keys. Data plane operations (querying, inserting, updating documents) use a separate per-account endpoint at https://{accountName}.documents.azure.com/ with a different SDK.

### Can I limit what my agent is allowed to do with the Cosmos DB API?

Yes. Because you self-host Jentic One, your own rules decide which Cosmos DB operations the agent may call and which Azure credentials it may use. Since the subscription, resource group, and account name are all URL path parameters, a rule can pin the agent to a single Cosmos DB account. You also choose the specific operations, so destructive ones like deleting an account or regenerating its keys stay out of reach unless you explicitly grant them.