# Managing your clients with projects

> Run one project per client with a company-level key, give each an allowance, daily and monthly limits and its own brand, top it up or reduce it, and read what it was charged.

Canonical guide: <https://engine.neraperla.com/docs/projects>

Raw Markdown: <https://engine.neraperla.com/docs/raw/projects.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

If you resell Blackpearl to your own clients, give each client a project. Your company keeps one balance, card, and auto-recharge, and each project gets its own spending controls, so one client running out never stops the others.

Every amount on this page is what your company balance is charged, in US dollars.

## Use a company-level API key

A company-level key acts in any of your projects. Owners and administrators create one in the console under **API keys**, by choosing **Company (all projects)**. Project keys keep working exactly as before.

When you create the key, choose its **default project**: the project used when a request doesn't name one. The default choice is **None**, which means every request must name its project. Keep None if you run a project per client: a forgotten header is then refused, instead of being run and charged against the wrong client.

With a company-level key, name the project on each request with the `Blackpearl-Project` header. It takes the project's id or its slug. One company-level key has one request-rate budget for every project it serves (see [Rate limits](https://engine.neraperla.com/docs/rate-limits)):

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/prospects" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Blackpearl-Project: client-a" \
  --header "Idempotency-Key: client-a-20261008-austin-pm" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign_name": "Austin property managers",
    "product_info": "Commercial security guard services.",
    "objective": "Find facilities and property managers at commercial real-estate firms in Austin, TX."
  }'
```

- When a request has no header, the project comes from the job, campaign, or audience it is about, then from the key's default project. Polling `GET /v1/jobs/{job_id}` therefore works with or without the header.
- Without a header and with no default project, requests that create work, and project-scoped reads and lists, fail with `400 project_required`.
- The projects and limits endpoints below work without it.
- An unknown id or slug returns `404 project_not_found`. Naming an archived project returns `403 project_archived`.
- If a key's default project is archived, requests that name no project and need one return `403 project_archived`; company-wide requests (projects, limits, charges, price estimates, and restoring the project) still work.
- A project key may send the header only with its own project's id or slug; any other value returns `403 forbidden`.

Idempotency keys are scoped per project, so reusing one for two clients never replays the wrong client's job.

## Create a project per client

Operation `create_project` creates a project. Pass your own client id as the `slug` if you like: up to 64 letters, digits, `.`, `_` and `-`, starting with a letter or digit, unique within your company, and not starting with `proj_`. Without a slug, one is made from the name, with `-2`, `-3` and so on added if it is taken. A slug can't be changed later, and an archived project keeps its slug.

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/projects" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "Client A", "slug": "client-a"}'
```

The response is the project with its `limits`. A new project starts with your company's new-project defaults (see [Company limits and defaults](#company-limits-and-defaults)). A slug already in use returns `409 conflict`.

`list_projects` returns your active projects, oldest first; pass `include_archived=true` to include archived ones. `get_project` reads one by id or slug. `update_project` renames a project, sets its default brand (see below), archives it with `{"archived": true}` so it can't run work, or restores it with `{"archived": false}`. Archiving keeps the project's history, allowance, and charges. An archived project runs no work from anywhere: the API, the console, connected Claude clients, or a campaign's schedule. It is read-only, not hidden: with a company-level key and no header, its jobs, results, events and exports stay readable, so a run in progress when you archive it can still be polled; a change addressed to its resources returns `403 project_archived`. The project operations on this page still work on it by id or slug with a company-level key: you can read it and its charges, rename it, top up or reduce its allowance, change its limits, and restore it. Its own project keys stop working. If an archived project is a company-level key's default project, the key keeps working for everything else, and a request that names no project is refused with `403 project_archived`.

## Give each client its own brand

Playbooks and documents are written as a seller: a brand profile. A request can name one with `brand_profile_id` or `brand_profile_key` (playbooks) or `brand` (documents). When it doesn't, the run sells as your company's default brand: the first brand your company created, unless you made another the default, or a placeholder "Blackpearl" profile if it has none. If you resell, that's your client's seller identity, so give each client project its own default brand:

1. Create the client's brand with `POST /v1/brands` (operation `create_brand_v1_brands_post`), naming the client's project in the `Blackpearl-Project` header. It returns a brand research job whose `input.brand_profile_id` is the new brand's id; the brand exists straight away, and the research fills in its guideline. Wait for the job to succeed before running the client's work: playbooks then get the researched brand as well as its name, and documents need it. Research is a run like any other: it needs the `brands` capability (check `GET /v1/capabilities`) and is charged to that project. Leave `is_default` false: it would change your company's default brand, not the client's. Brands belong to your company, not to a project: any of your keys, including a project key, can list and read every brand. If brand names are sensitive, don't give a client a project key of its own. See [Brands](https://engine.neraperla.com/docs/brands).

   ```bash
   curl --fail-with-body --silent --show-error \
     --request POST "$BLACKPEARL_API_BASE_URL/v1/brands" \
     --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
     --header "Blackpearl-Project: client-a" \
     --header "Idempotency-Key: client-a-brand" \
     --header "Content-Type: application/json" \
     --data '{"company_name": "Client A Security", "website_url": "https://client-a.example"}'
   ```

2. Set it as the project's `default_brand_profile_id`, when you create the project or later with `update_project`:

   ```bash
   curl --fail-with-body --silent --show-error \
     --request PATCH "$BLACKPEARL_API_BASE_URL/v1/projects/client-a" \
     --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
     --header "Content-Type: application/json" \
     --data '{"default_brand_profile_id": "brand_9d2e4f6a8b0c1d3e"}'
   ```

   The response is the project, with `"default_brand_profile_id": "brand_9d2e4f6a8b0c1d3e"`. Send `null` to clear it; leave the field out to keep it unchanged.

From then on, a playbook or document for that project that names no brand sells as the client. The brand is chosen in this order:

1. the brand in the request;
2. for playbooks, the brand of the organization playbook template the request selects, if it has one;
3. the project's `default_brand_profile_id`;
4. your company's default brand.

The default must be an active brand of your company: another company's brand or an unknown id returns `404 brand_profile_not_found`, and an archived one `409 brand_profile_archived`. If you archive a brand that is still a project's default, that project's runs that name no brand are refused with `409 brand_profile_archived` rather than written for the wrong seller. Set a new default, or name a brand in the request.

The number of active brands per company is limited; past the limit, creating a brand returns `409 conflict`. Archive brands you no longer use, or contact support if you need more for your clients.

## Give the project an allowance

An allowance is a spending limit for one project. It isn't money: the money stays in your company balance. It never resets, and you top it up when your client renews.

Turn it on with `set_project_limits`. Every field is required; send `null` for no limit (a daily or monthly limit must be above $0, and a `min_to_start_usd` of `0` means no minimum):

```bash
curl --fail-with-body --silent --show-error \
  --request PUT "$BLACKPEARL_API_BASE_URL/v1/projects/client-a/limits" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "allowance_enabled": true,
    "min_to_start_usd": 5,
    "daily_limit_usd": 50,
    "monthly_limit_usd": null
  }'
```

Then top it up with `top_up_project_allowance`:

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/projects/client-a/allowance" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"amount_usd": 100, "reference": "invoice-1042", "note": "October renewal"}'
```

`amount_usd` is from $0.01 to $1,000,000; outside that range returns `422 invalid_request`. `reference` is your own id for the top-up, such as an invoice or payment id: up to 128 letters, digits, `.`, `_`, `:`, `/` and `-`, starting with a letter or digit. It makes the call safe to retry:

- A new reference adds the amount and returns `201` with `"replayed": false`.
- The same reference and amount again adds nothing and returns `200` with the original top-up and `"replayed": true`.
- The same reference with a different amount, or a reference already used for a reduction, returns `409 conflict`.

Every top-up is kept in an append-only log. `get_project_allowance` returns the allowance and its log, newest first, with cursor pagination, so you can reconcile it against your clients' payments and refunds.

### Reduce an allowance when you refund a client

When you refund your client, take the refunded amount off their project's allowance with `reduce_project_allowance`. Send the amount as a positive number:

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/projects/client-a/allowance/reductions" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"amount_usd": 40, "reference": "refund-1042", "note": "Refund of unused October allowance"}'
```

- `amount_usd` and `reference` follow the same rules as for a top-up. The same reference and amount again takes nothing more off and returns `200` with `"replayed": true`. References are unique per project across top-ups and reductions, so a reference already used for a different amount or for a top-up returns `409 conflict`.
- A reduction can't take the project's total granted below zero. Taking off more than has been granted returns `409 conflict` and records nothing.
- It can take what remains below zero when the client has already spent more than the new total. Runs in progress finish and are charged; the project's next runs are refused with `budget_exceeded` until you top it up. Other projects aren't affected.

A reduction appears in the log with `"kind": "reduction"` and a negative `amount_usd`; top-ups have `"kind": "top_up"`. The amounts in the log add up to `granted_usd`.

The allowance object reports:

- `granted_usd`: the total of every top-up less every reduction;
- `charged_usd`: what the project's runs were charged since the allowance was first enabled. Turning the allowance off and on again doesn't restart this count: charges made while it was off still count;
- `held_usd`: what runs still in progress hold (see below);
- `remaining_usd`: granted minus charged, which can go negative after an overshooting run or a reduction;
- `available_usd`: remaining minus held. This is what a new run is checked against.

## Minimum to start and parallel runs

A run's price isn't known until it finishes, so the minimum to start (`min_to_start_usd`) sets how much allowance a run needs before it starts. Each run in progress holds that amount until it is charged, so starting several runs at once needs that many times the minimum. For example, with $12 available and a $5 minimum, two runs can start and a third is refused until one finishes.

Without a minimum, a run starts whenever the available allowance is above $0. Runs then hold nothing, so several runs started at the same moment can all start and together take the allowance further below zero. Set a minimum if you start runs in parallel. The minimum applies only while the project's allowance is on.

Several runs, in one project or in different ones, can be in progress at the same time when your company is on an uncapped usage tier, as reseller accounts are. On a capped tier, the whole company can have only one run in progress at a time: another start is refused with `429 budget_exceeded` (`details.scope: usage_tier`) until that run finishes. See [Rate limits](https://engine.neraperla.com/docs/rate-limits#usage-tiers).

A run that has started is never cut off. It finishes, keeps its results, and is charged in full, even if that takes the project's allowance below zero. The project's next runs are refused until you top it up. Other projects aren't affected.

## Daily and monthly limits

`daily_limit_usd` and `monthly_limit_usd` cap a project's charges per UTC day and per UTC month. They reset at `00:00:00 UTC` each day and on the first of each month. They work alongside the allowance: a run must pass both.

A limit is checked when a run starts, against what has already been charged; unlike the minimum to start, it holds nothing for runs in progress. Runs already in progress when a limit is reached all finish and are charged, so with several runs in parallel the total can pass the limit by more than one run. A run's charge counts toward the UTC day and month in which it finishes.

`get_project_limits` returns every limit with what is left:

```json
{
  "project_id": "proj_3f9c1a7d2b8e4c11",
  "allowance": {
    "enabled": true,
    "granted_usd": 200.0,
    "charged_usd": 63.1,
    "held_usd": 5.0,
    "remaining_usd": 136.9,
    "available_usd": 131.9,
    "started_at": "2026-10-01T09:30:00Z"
  },
  "min_to_start_usd": 5.0,
  "daily": {"limit_usd": 50.0, "spend_usd": 12.4, "remaining_usd": 37.6, "resets_at": "2026-10-09T00:00:00Z"},
  "monthly": {"limit_usd": null, "spend_usd": 63.1, "remaining_usd": null, "resets_at": "2026-11-01T00:00:00Z"}
}
```

Daily and monthly limits are hard budgets, so email alerts go out at 80% and 100%, and they also appear in the budgets list on the console **Costs** page. Editing or deleting one there changes or removes the limit, and turning off its hard limit there leaves only an alert, so `get_project_limits` then reports no limit.

## Company limits and defaults

`get_company_limits` and `set_company_limits` manage limits across all of your projects, plus what new projects start with. Both need a company-level key. As with a project's limits, every field of `set_company_limits` is required, including every field of `new_project_defaults`; send `null` for no limit:

```bash
curl --fail-with-body --silent --show-error \
  --request PUT "$BLACKPEARL_API_BASE_URL/v1/limits" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "daily_limit_usd": 300,
    "monthly_limit_usd": 3000,
    "new_project_defaults": {
      "allowance_enabled": true,
      "starting_allowance_usd": 0,
      "daily_limit_usd": null,
      "monthly_limit_usd": null,
      "min_to_start_usd": 5
    }
  }'
```

When a company limit is reached, every project's new runs are refused until it resets.

New-project defaults apply only to projects created afterwards, over the API or in the console. With `allowance_enabled: true` and a `starting_allowance_usd` of `0`, a new client can't run anything until you top up its allowance. A starting allowance above `0` is recorded as the project's first top-up, with the reference `starting-allowance`, so don't use that reference for your own top-ups. Until you set defaults, new projects have no allowance and no limits, which is how projects behaved before.

## When a run is refused

Every limit refuses with the existing `429 budget_exceeded` error. Don't retry it automatically: top up, raise the limit, or wait for `resets_at`. `error.details` says which limit refused the run. When several would, it reports one, in this order: the project's allowance (only a top-up restores it), the project's monthly then daily limit, then the company's monthly then daily limit. A hard budget for one capability, set in the console, comes after the all-capability limits of the same scope:

| `details` field | Meaning |
| --- | --- |
| `scope` | `project` for a project's allowance or limits, `organization` for a company limit. |
| `kind` | `allowance` (used up), `min_to_start` (less available than the minimum), `day`, or `month`. |
| `project_id` | The project, for project-scope refusals. |
| `limit_usd`, `spend_usd`, `remaining_usd` | In charged amounts. For an allowance, `limit_usd` is the total granted and `remaining_usd` is the available amount. |
| `held_usd`, `min_to_start_usd` | Allowance refusals only. |
| `resets_at` | When a daily or monthly limit resets; `null` for an allowance, which only a top-up restores. |

```json
{
  "error": {
    "code": "budget_exceeded",
    "message": "A spending limit for this scope has been reached",
    "request_id": "req_6f1c2d3e4a5b",
    "details": {
      "scope": "project",
      "kind": "min_to_start",
      "project_id": "proj_3f9c1a7d2b8e4c11",
      "period": null,
      "capability_key": null,
      "limit_usd": 200.0,
      "spend_usd": 196.2,
      "held_usd": 0.0,
      "remaining_usd": 3.8,
      "min_to_start_usd": 5.0,
      "hard_limit": true,
      "resets_at": null
    }
  }
}
```

The company balance still applies: when it reaches $0, every project's runs are refused with `402 insufficient_credits`, unless one of the limits above refuses the run first. See [Limits, budgets, and usage](https://engine.neraperla.com/docs/usage-quotas).

## Read a project's charges

`list_project_charges` lists what each of a project's runs was charged, newest first. Filter with `from` and `to` (UTC) and page with `cursor`. Each entry is exactly the entry the company's charge history shows for that run, with the same fields and signs: a run charge is a `debit` whose `amount_usd` is negative, because it takes money from the company balance, and `balance_after_usd` is the company balance right after it.

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/projects/client-a/charges?from=2026-10-01T00:00:00Z&limit=100" \
  --header "Authorization: Bearer $BLACKPEARL_COMPANY_KEY"
```

```json
{
  "charges": [
    {
      "id": "ctx_5a8b2c9d1e0f3a4b",
      "type": "debit",
      "amount_usd": -2.43,
      "balance_after_usd": 412.57,
      "job_id": "job_0b1c2d3e4f5a6b7c",
      "capability": "prospecting",
      "project_id": "proj_3f9c1a7d2b8e4c11",
      "project_slug": "client-a",
      "project_name": "Client A",
      "created_at": "2026-10-08T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Match `job_id` to the job you created to attribute each charge to your client's request. A client's spend is the sum of its entries' `amount_usd` with the sign flipped.

## Read the company's charge history

`list_charges` (`GET /v1/charges`) lists every change to your company balance, newest first, each with the balance after it: run charges, credit purchases, gifts, adjustments, and refunds. See [Read your charge history](https://engine.neraperla.com/docs/billing#read-your-charge-history) for the fields and filters.

- Narrow it to one client with `project=client-a` (id or slug) or the `Blackpearl-Project` header. Only run charges belong to a project, so a project's entries are exactly what `list_project_charges` lists: the same entries, fields and signs. Use either to reconcile a client's spend.
- A company key that names no project sees every entry, even if it has a default project. A project key sees only its own project's run charges; naming another project returns `403 forbidden`.

## Alerts

Your billing contacts get an email when a project's remaining allowance falls below 20% of everything granted to it, and again when it is used up or below its minimum to start, including straight after a reduction. Each alert is sent once per allowance level; a top-up or reduction re-arms it. Daily and monthly limits send budget alerts at 80% and 100%; a project limit's alert names the project, and a company limit's alert says it covers every project.

## Who can manage projects

- Over the API, only a company-level key can create, rename, or archive projects, set their default brand, and change allowances and limits. A project key can read only its own project, limits, allowance, and charges; any other projects or limits call returns `403 forbidden`.
- A project key still sees some company-wide information: every brand of your company (brands belong to the company, not a project), the company balance (`credits.balance_usd` in `GET /v1/usage`, and `balance_after_usd` on each charge), company-wide monthly budgets and the usage tier in `GET /v1/usage`, and price estimates. Give a client a project key of its own only if it may see these.
- In the console, owners and administrators create and archive projects and keys. Restore an archived project over the API with `update_project`. Owners, administrators, and billing members manage allowances and limits on **Settings → Projects**.
