Skip to content
Docs

Create Agency Client

Create a client workspace.

POST/api/v1/agency/clients

Requires an API key with the write scope.

Only API keys of an Agency workspace can call this endpoint (403 agency_required otherwise). The call always runs in the key's own workspace; X-Workspace-Id is ignored. Writes also need a key created by the agency workspace owner (403 agency_owner_required otherwise).

Creating a client counts toward the plan's workspace limit. The new workspace starts on the free plan and the agency owner is its owner.

Body Parameters#

namestringbodyrequired
Client name, 1 to 100 characters.

Response#

Returns the client with a 201 status code.

dataobject
Show data
idstring
Workspace id.
namestring
Workspace name.
slugstring
URL slug.

Each create is recorded as an audit.agency_client.created event with the key as the actor, readable through the audit log.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: write
403agency_required, agency_owner_required, or upgrade_required when the workspace limit is reached
422name is missing or longer than 100 characters

Rate Limit#

  • 120 requests per minute, shared by every write call in your workspace. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (write).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Was this page helpful?
View as MarkdownLast updated November 4, 2026