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

# Agency API overview

> Provision sub-account workspaces, assign plans and add-ons, and subscribe to lifecycle events: the whitelabel reseller API.

The **Agency API** is for whitelabel resellers. It lets you manage your sub-accounts
programmatically: provision a customer workspace, assign it a plan, grant add-ons, suspend or
restore it, and subscribe to its lifecycle events. The agency console does most of this too;
creating a workspace is the exception, since the console has no create button and customers
normally arrive by signing up on your branded domain.

```bash theme={"dark"}
curl https://dash.dmly.io/api/agency/v1/workspaces \
  -H "x-api-key: dmly_ag_xxxxxxxxxxxx"
```

<Note>
  This is a **separate surface** from the [workspace REST API](/api-reference/introduction). It has
  its own base URL, its own key, and its own webhooks. An agency key manages your sub-accounts; a
  workspace key acts *inside* one workspace. The two are not interchangeable.
</Note>

## Base URL

All endpoints live under a single version prefix:

```
https://dash.dmly.io/api/agency/v1
```

## What you can manage

<Columns cols={2}>
  <Card title="Sub-accounts" icon="users-gear">
    Provision a customer workspace with its owner, rename it, and suspend or restore access.
  </Card>

  <Card title="Subscriptions & add-ons" icon="layer-group">
    Assign a base plan to a sub-account and grant or revoke add-ons on top of it.
  </Card>

  <Card title="Plans" icon="tags">
    List your plan and add-on catalogue to discover the uuids the other endpoints take.
  </Card>

  <Card title="Webhooks" icon="bolt">
    Register endpoints and subscribe to sub-account lifecycle events.
  </Card>
</Columns>

## How it works

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/agency-authentication">
    One agency API key (`dmly_ag_…`) authenticates you and scopes every request to your own
    sub-accounts.
  </Card>

  <Card title="Webhook events" icon="bolt" href="/api-reference/agency-webhooks">
    Six sub-account lifecycle events, signed and delivered to your endpoint.
  </Card>
</Columns>

## Conventions

* **Identifiers are UUIDs.** Sub-accounts, plans, add-ons and webhook endpoints are addressed by
  their public `uuid`.
* **You only ever see your own.** Every request is scoped to the agency the key belongs to; an
  unknown uuid, or one belonging to another agency, returns `404`.
* **Lists paginate** with `?per_page` and `?page`, default 25, capped at 100. `?limit` is not
  accepted here (that alias exists only on the workspace REST API), and an unrecognised parameter
  is ignored, so `?limit=100` quietly returns 25 rows. Only `GET /workspaces` is paginated; the
  plan catalogue and webhook lists are short and return a plain `data` array with no `meta`.
* **Rate limit:** 120 requests per minute per agency key. See
  [Authentication](/api-reference/agency-authentication#rate-limit).
* **JSON in, JSON out.** Send `Content-Type: application/json` on writes.

## Billing model

Sub-account subscriptions are **agency-billed**: assigning a plan or granting an add-on copies the
plan's limits onto the workspace directly. There is no customer Stripe checkout in this flow, and
changing a plan never un-suspends a locked sub-account. You settle with DMLY; how you bill your own
customers is up to you.

## Getting a key

Mint an agency key from the agency console under **Configuration → API**. See
[Authentication](/api-reference/agency-authentication). The whole surface can also be disabled
fleet-wide during an incident, in which case every endpoint returns `503` until it is switched back
on.

## Try it

Every endpoint page has a playground. Paste an agency key into the **Authorization** panel and you
can call the live API straight from these docs.

<Warning>
  The playground calls the live API and **provisions real sub-accounts**. Creating a workspace makes
  a real one that counts toward your agency's limits, so clean up anything you create while testing.
</Warning>