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

# Billing API Overview

> Discover the billing mode and manage member plans, workspace and group limits, and agent budgets from your own systems

The Billing API lets you change member plans, workspace and group limits, and agent budgets from your own systems. Use it when an admin request should update Langdock without someone opening the usage settings. You can also list usage requests and decline one that is still waiting.

The [User Management API](https://docs.langdock.com/en/developer/user-management-api/user-management-overview.md) invites people, changes roles, and deactivates members. This API does not. It also does not change group membership.

> [!NOTE]
>
> Call the routes below when `GET /billing/v1/mode` returns `bring-your-own-keys`. Dedicated deployments always return that mode, including when Langdock manages the model keys. Amounts are US dollars. Cloud workspaces can grant the **Billing API** scope only where Langdock has enabled it. If the mode is different, these routes return `409`.

## Before You Start

* **API key scope**: `BILLING_API` on a workspace API key. In the scope picker the scope is labeled **Billing API** and sits in the **Billing** group, after **User management** and before **Audit log**. Personal keys cannot take this scope. Existing workspace keys do not gain it on their own.
* **Owner**: The key owner is a service account that has not been deleted and has an active Admin membership. Writes run as that service account. If that membership is gone, calls return `403` with `code` `BILLING_API_ADMIN_REQUIRED`.
* **Names and emails**: User objects always include `id`, the plan, and limits. They include `email` and `name` only when the same key also has `USER_MANAGEMENT_API`. Filtering users by `email` without that scope returns `403` with `code` `USER_MANAGEMENT_API_REQUIRED`.

Start with mode discovery, then call only the routes for that mode. The other mode returns `409` with `code` `BILLING_MODE_MISMATCH` and the workspace mode in `details.mode`.

## Base URL

```
https://api.langdock.com
```

> [!WARNING]
>
> **Dedicated deployments**
>
> Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.

## Billing mode

```bash theme={null}
curl https://api.langdock.com/billing/v1/mode \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{ "mode": "bring-your-own-keys", "currency": "USD" }
```

Plans in this mode are `standard` (**Standard**) and `power_user` (**Power user**). There is no seats route. A path that does not exist in this mode, such as a seats path, returns `404`.

## Limits

Send and read a limit in one of these shapes. Only `limited` includes `amount`.

```json theme={null}
{ "type": "limited", "amount": 80 }
```

```json theme={null}
{ "type": "unlimited" }
```

A limited workspace amount must be greater than zero. A limited amount on a plan, a member, or a group may be zero. A limited agent budget must be greater than zero.

Extra usage budgets in this mode also accept `{ "type": "none" }`. Agent budgets accept `none` as well. `none` removes that extra allowance, or removes the separate agent budget.

A `PATCH` must include at least one field you can write. Fields you omit stay as they are, including a plan you leave out of `monthlyBudgetPerPlan`. Unknown fields are rejected.

## Lists and spend

Lists default to 50 items. Set `limit` from 1 to 250. Pass `cursor` from the previous page's `nextCursor`, and keep the same filters. `nextCursor` is omitted on the last page. Treat the cursor as opaque.

`GET` returns spend when the workspace shows per user spend. When that spend is hidden, the spend field is `null`. User, settings, and agent writes always return `null` for spend, so a write that already succeeded does not fail while spend is loading. Read the resource again to get spend.

## Available endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/billing/v1/mode` | Read the billing mode and currency |
| `GET`, `PATCH` | `/billing/v1/bring-your-own-keys/settings` | [Read and update workspace settings](https://docs.langdock.com/en/developer/billing-api/get-settings.md) |
| `GET` | `/billing/v1/bring-your-own-keys/plans` | [Count active members on each plan](https://docs.langdock.com/en/developer/billing-api/get-plans.md) |
| `GET` | `/billing/v1/bring-your-own-keys/users` | [List members](https://docs.langdock.com/en/developer/billing-api/list-users.md) |
| `GET` | `/billing/v1/bring-your-own-keys/users/{userId}` | [Read one member](https://docs.langdock.com/en/developer/billing-api/get-user.md) |
| `PUT` | `/billing/v1/bring-your-own-keys/users/{userId}/plan` | [Set a member's plan](https://docs.langdock.com/en/developer/billing-api/set-user-plan.md) |
| `PUT` | `/billing/v1/bring-your-own-keys/users/{userId}/extra-usage-budget` | [Set an extra usage budget](https://docs.langdock.com/en/developer/billing-api/set-user-extra-usage-budget.md) |
| `POST` | `/billing/v1/bring-your-own-keys/users/plan/bulk` | [Set plans for up to 500 members](https://docs.langdock.com/en/developer/billing-api/bulk-set-user-plans.md) |
| `GET` | `/billing/v1/bring-your-own-keys/usage-requests` | [List usage requests](https://docs.langdock.com/en/developer/billing-api/list-usage-requests.md) |
| `GET` | `/billing/v1/bring-your-own-keys/usage-requests/{requestId}` | [Read one usage request](https://docs.langdock.com/en/developer/billing-api/get-usage-request.md) |
| `POST` | `/billing/v1/bring-your-own-keys/usage-requests/{requestId}/dismiss` | [Decline a waiting usage request](https://docs.langdock.com/en/developer/billing-api/dismiss-usage-request.md) |
| `GET` | `/billing/v1/bring-your-own-keys/groups` | [List groups](https://docs.langdock.com/en/developer/billing-api/list-groups.md) |
| `GET` | `/billing/v1/bring-your-own-keys/groups/{groupId}` | [Read one group](https://docs.langdock.com/en/developer/billing-api/get-group.md) |
| `PUT` | `/billing/v1/bring-your-own-keys/groups/{groupId}/monthly-budget` | [Set a group's monthly budget](https://docs.langdock.com/en/developer/billing-api/set-group-monthly-budget.md) |
| `GET` | `/billing/v1/bring-your-own-keys/agents` | [List agent budgets](https://docs.langdock.com/en/developer/billing-api/list-agents.md) |
| `GET`, `PATCH` | `/billing/v1/bring-your-own-keys/agents/{agentId}` | [Read and update an agent budget](https://docs.langdock.com/en/developer/billing-api/get-agent.md) |

## Errors

| Status | When |
| - | - |
| `400` | The input is invalid, a field is unknown, a `PATCH` is empty, a limit is invalid, a bulk list includes someone who is not an active human member, or the cursor is not from this workspace |
| `401` | The API key is missing or invalid |
| `403` | The key lacks the Billing scope, is a personal key, the owner is not an active admin service account, or an email filter lacks the User Management scope |
| `404` | The resource is outside this workspace, the user is not an active human member, the agent is hidden, the path does not exist in this mode, or a named usage request is not that member's |
| `409` | The path mode is not the workspace mode, the usage request is no longer pending, or the change does not raise the allowance for a named usage request |
| `429` | The API rate limit was exceeded |

> [!NOTE]
>
> Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md).


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