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

# Agencies and Client Workspaces

> For agencies, resellers, white-label partners and enterprises: create client workspaces, distribute credits and identities, and buy more capacity

## Who this is for

These endpoints are for **organizations** and their **client workspaces** only. An organization is an agency, reseller, white-label partner or enterprise that runs several Enginy workspaces (its clients) under one contract.

* `GET /v1/workspace` works for every workspace. It tells you whether the workspace belongs to an organization, how it is billed and how it gets more capacity.
* The `/v1/organization` endpoints work only from a workspace that belongs to an organization, with an API key whose creator holds an organization role. The role is checked first: without one, reads answer `403` `ORGANIZATION_READ_FORBIDDEN` and writes `403` `ORGANIZATION_ADMIN_FORBIDDEN`. With one, a workspace that is not in an organization (it left, or never joined) gets `404` `NOT_IN_ORGANIZATION`.

> [!NOTE]
>
> **Upsell and management only.** You can create clients, redistribute capacity between them, and buy or
> request more. No endpoint lowers your organization's contracted quota, downgrades a plan or cancels
> anything. To reduce what you pay, contact your Enginy account manager.

## Permissions

Two checks apply to every organization call:

| Check | Read endpoints | Write endpoints |
| - | - | - |
| API key scope | `WORKSPACE_READ` | `WORKSPACE_WRITE` |
| Creator's access | `ORGANIZATION_MANAGER` or `ORGANIZATION_ADMIN` role | `ORGANIZATION_ADMIN` role |

The access check reads the role of the person who created the API key (the connected user for MCP), in the workspace the key belongs to, on every call. A key never carries more than its creator holds now: revoking their organization role refuses their keys on the next call. A workspace admin role alone gives no organization access.

`GET /v1/workspace` needs only the `WORKSPACE_READ` scope.

Scopes do not include each other: a key that both reads and writes needs `WORKSPACE_READ` and `WORKSPACE_WRITE` (or `ALL`). MCP grants are different: a write scope there includes its read scope.

Refusals carry the reason in `details.code`:

```json theme={null}
{
  "status": "error",
  "message": "Not enough unallocated credits in the workspace pool (2000 available)",
  "details": { "code": "POOL_HEADROOM_EXCEEDED" }
}
```

| Status | Codes |
| - | - |
| `403` | `ORGANIZATION_READ_FORBIDDEN`, `ORGANIZATION_ADMIN_FORBIDDEN`, `ACCOUNT_BILLED_SELF_SERVE`, `PURCHASES_ARE_REQUESTED`, `PURCHASE_NEEDS_BILLING_AGREEMENT`, `NO_CONTRACT_VIEW` |
| `404` | `NOT_IN_ORGANIZATION`, `ORGANIZATION_NOT_FOUND`, `ACCOUNT_NOT_FOUND` |
| `412` | `QUOTA_NOT_SET` (Enginy has not set this quota yet) |
| `429` | Rate limit exceeded. Wait `X-RateLimit-Retry-After-Seconds` and retry. |
| `400` | `POOL_HEADROOM_EXCEEDED`, `MOVE_EXCEEDS_BUDGET`, `MOVE_EXCEEDS_IDENTITY_SLOTS`, `IDENTITY_CAP_BELOW_CONNECTED`, `BELOW_ADD_ON_CREDITS`, `ACCOUNT_LIMIT_REACHED`, `CREDITS_NOT_IN_INCREMENTS`, `PURCHASE_NEEDS_QUOTA`, `CAPACITY_IS_PURCHASED` |

## Self-serve and Sales-led billing

Every workspace is billed one of two ways:

| Billing | How it gets more capacity |
| - | - |
| **Self-serve** (`STRIPE_PLG`): a plan bought with Stripe | An admin upgrades its plan or adds credits in the app. Its plan sets its capacity, so its organization cannot move credits or identities to or from it. |
| **Sales-led** (`SALES_LED`, `PARTNER`): a contract or deal | Its organization admins allocate capacity from the organization pool, and the organization buys or requests more. Standalone Sales-led workspaces buy in the app. |

`GET /v1/workspace` returns `billing.model` and `upsell.path`. `GET /v1/organization/clients` returns `billedSelfServe` for each client. Capacity changes on a self-serve client are refused with `ACCOUNT_BILLED_SELF_SERVE`. Clients you create with the API are Sales-led, billed on the organization deal.

How the organization itself gets more depends on `capabilities.purchaseMode` from `GET /v1/organization`:

* `self-serve` (agencies, resellers, white-label partners): buy with `POST /v1/organization/capacity/purchases`. A billing agreement with Enginy is required. A purchase commits and is billed at once; one purchase adds at most 1,000,000 credits or 1,000 identities.
* `request` (enterprises): ask with `POST /v1/organization/capacity/requests`. Nothing changes until Enginy answers.

## Read your workspace

```bash theme={null}
curl "https://openapi.enginy.ai/v1/workspace" -H "x-api-key: $ENGINY_API_KEY"
```

| Field | Notes |
| - | - |
| `identities` | Identity slots in use, the maximum and how many are free. |
| `credits` | Monthly plan and add-on credits. |
| `billing` | `authority` and `model` (`self-serve` or `sales-led`). |
| `organization` | The organization, its `purchaseMode` and your `callerRole`; `null` for a standalone workspace. |
| `appUrl`, `host` | Where the workspace's users open the app: your white-label custom domain when your organization has one. |
| `upsell` | `path` (`self-serve-billing`, `purchase` or `request`), `creditsUrl` to add credits and, for self-serve workspaces, `upgradePlanUrl`. Upgrade links only. |

## Create a client workspace

```bash theme={null}
curl -X POST "https://openapi.enginy.ai/v1/organization/clients" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "companyWebsite": "acme.com",
    "initialMonthlyCredits": 5000,
    "initialIdentities": 2
  }'
```

The new workspace counts against the organization's client quota (`ACCOUNT_LIMIT_REACHED` when full), and its initial credits and identities come from the organization pools. The API key creator becomes its first admin, and the website sets its logo. The AI playbook is not filled automatically: fill it with `PUT /v1/ai-playbook` using an API key of the new workspace, or in the app. To work in the new workspace through the API, create an API key in it.

## Distribute capacity

List clients with their capacity and the organization pools:

```bash theme={null}
curl "https://openapi.enginy.ai/v1/organization/clients?take=100" -H "x-api-key: $ENGINY_API_KEY"
```

Set a client's cap to an absolute value. The difference moves to or from the organization's unallocated pool:

```bash theme={null}
curl -X PUT "https://openapi.enginy.ai/v1/organization/clients/123/capacity" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "CREDITS", "value": 8000, "note": "Q4 campaign" }'
```

Or move an amount between two clients (`null` is the pool):

```bash theme={null}
curl -X POST "https://openapi.enginy.ai/v1/organization/capacity/moves" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "IDENTITIES", "fromClientId": 123, "toClientId": 456, "amount": 1 }'
```

* Credits moved mid-month are delivered or retracted right away (`immediateAmount`). A move out never takes more than the client's unspent credits this month.
* A client's identity cap cannot go below its connected identities.
* Lowering a client's cap returns capacity to the pool for another client. It does not lower what the organization pays.
* Every change is recorded in `GET /v1/organization/capacity/history`.

## Get more capacity

```bash theme={null}
curl -X POST "https://openapi.enginy.ai/v1/organization/capacity/purchases" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "CREDITS", "amount": 10000 }'
```

The quota grows by `amount` and `additionalMonthlyCost` is added to your monthly invoice. Allocate the new capacity to clients afterwards. Credits are bought in batches of 1,000. Enterprises send the same body to `POST /v1/organization/capacity/requests`.

Enterprises with a contract view can compare contracted, allocated and consumed capacity with `GET /v1/organization/contract`.


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