Agencies and Client Workspaces

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.

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:

{
  "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

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

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:

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:

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):

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

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.

API documentation

Endpoints

Agencies and Client Workspaces

Who this is for

Permissions

Self-serve and Sales-led billing

Read your workspace

Create a client workspace

Distribute capacity

Get more capacity

​Who this is for

​Permissions

​Self-serve and Sales-led billing

​Read your workspace

​Create a client workspace

​Distribute capacity

​Get more capacity

Who this is for

Permissions

Self-serve and Sales-led billing

Read your workspace

Create a client workspace

Distribute capacity

Get more capacity