# Public API Changelog

Observable changes to the public `/v1` API are recorded here. Internal refactors
that do not affect the public contract do not need an entry.

## Unreleased

### Prospecting keeps more of each search

- A result holds up to 5,000 prospects (was 500). A search whose agent
  delivered more than 500 contacts used to return only the first 500 in
  the agent's order; it now returns all of them.
- A run whose request has a `query` now also gives the agent your
  `product_info`. Before, the `query` alone was the brief, so the agent
  judged fit without knowing what you sell.
- A run no longer fails with `prospecting_backend_unavailable` when its
  connection to the search engine drops mid-run: it reconnects to the same
  search and completes. It is charged as a normal run.

### Deprecations

These fields are marked `deprecated: true` in the OpenAPI contract and will be
removed in a future API version. They are still accepted or returned, so
existing integrations keep working; stop sending or reading them.

- `limit` on `POST /v1/prospects` is ignored. It no longer goes into the
  agent's brief, so it doesn't change the search or cap the result.
- `min_qualification_score` on `POST /v1/prospects` is ignored, as before: no
  prospect is dropped for its score.
- `qualification.confidence` is `null`, and `enrichment.confidence` is now
  always `null`: the engine reports no confidence and doesn't validate
  emails.
- `evidence[].confidence` is a fixed placeholder (`0.75`, or `0.7` for a
  match rationale), not a measurement.
- The CSV export's `Confidence` column is always empty; it stays so the
  later columns keep their positions.
- The console no longer shows confidence, and its new-run form no longer
  has a prospect-count field. The Claude connector's `run_prospecting` no
  longer takes `limit`.

### Prospecting results carry more of the engine's own data

- `qualification.score` is now the search agent's own fit score (its 0–10
  score divided by 10) on current runs, instead of `0.9` for every qualified
  prospect. Scores vary within a run and aren't comparable across runs.
- `qualification.confidence` is `null` on new prospects (it was previously a
  fixed `0.8`), and `enrichment.confidence` is `null` (it was previously
  `0.8` for every email found). The type of both is now `number | null`, for
  audience members too: check clients that read them as numbers. Both are
  deprecated (see Deprecations).
- `qualification.reason` is the engine's reason for the match. It no longer
  repeats the company description or industry; when the engine gave nothing
  more specific, it is the prospect's evidence text.
- New `profile.company` fields: `employee_range` (the source's employee band,
  such as `1001 to 5000`), `revenue_range` (its annual revenue band) and
  `intents` (buying-intent topics matched for the company; always a list,
  empty when none). `headcount` remains set only for an exact count.
- `profile.location` is the contact's own location when their record has one,
  instead of always the company's.
- New `agent_summary` on the result (`null` when the run reported none): the agent's results `title`,
  closing `message` (Markdown) and follow-up `suggestions`, served without
  contact-verification claims.
- The CSV export gains `Employees`, `Revenue` and `Intents` columns after
  `Phone`.
- The run's live thread no longer addresses the reader by the backend
  account's name.

### Prospecting returns the agent's full list

- The agent is asked for the full list it can find instead of "up to
  `limit`". A run is still priced for the whole search, so most runs now
  return well over a hundred prospects. `limit` is deprecated and ignored
  (see Deprecations).
- A result holds up to 500 prospects (was 100; since raised to 5,000).
- The Claude connector's `get_job_results` returns a prospecting result's
  prospects 50 at a time, with a `prospects_page` (`total`, `offset`,
  `count`, `next_cursor`); pass `next_cursor` back as `cursor`.

### More results from a search

- Continuations (`POST /v1/jobs/{parent_job_id}/continuations`, Preview) of a
  run made by the prospect agent now run: each round is a follow-up in the
  parent run's own search, asking for more new prospects and excluding the
  companies its lineage already delivered. The child returns only prospects
  its lineage hasn't delivered, reports each round in `research`, and is
  charged for every round's search work. A continuation that finds nothing
  new fails and is not charged (`error_code` null). A search runs one
  continuation at a time: a second one while one is queued or running gets
  the new `409 prospecting_continuation_in_progress` (retry after it
  finishes).
- New prospect fields `previously_delivered` and `previously_delivered_job_id`
  flag a contact one of the project's 50 most recent earlier runs already
  delivered.

## 2026-10-10

### Projects as client sub-accounts

All of this is additive: project keys behave as before, and only the new key
type can produce the new error codes. See the Projects guide.

- **Company-level API keys** (created in the console by owners and
  administrators) act in the project named by the new `Blackpearl-Project`
  request header (id or slug). Without the header, a request about one job,
  campaign or audience uses that resource's project, and any other request
  uses the key's default project, if one was chosen when the key was created
  (none by default). A request that needs a project and has none fails with
  `400 project_required`; an unknown project fails with
  `404 project_not_found`, and an unknown job, campaign or audience with
  `404 not_found`. A project key may send the header only with its own
  project, and gets `403 forbidden` for any other project, whether or not it
  exists.
- **Projects over the API:** `GET`/`POST /v1/projects` and
  `GET`/`PATCH /v1/projects/{project_ref}` (rename, set a default brand,
  archive, restore). Names are trimmed and can't be blank
  (`422 invalid_request`). Two requests creating the same slug at once get
  one project and one `409 conflict`; without a slug, the second gets the
  next free one.
- **Archived projects** run no work from any surface, including connected
  Claude clients and campaign schedules. They are read-only: a company-level
  key can still read their jobs, results, events and exports by id, so a run
  in progress when the project was archived can still be polled, while
  changes and new work in them return `403 project_archived`. A company-level
  key whose default project is archived keeps working for company-wide calls
  and for restoring the project; a call that needs a project and names none
  gets `403 project_archived`.
- **Per-project allowance** (a spending limit that never resets),
  **minimum to start** (held by each run in progress) and **daily and
  monthly limits**: `GET`/`PUT /v1/projects/{project_ref}/limits`, idempotent
  top-ups with `POST /v1/projects/{project_ref}/allowance` (keyed by
  `reference`; a replay returns `200`), and the log with `GET`.
- **Allowance reductions:** `POST /v1/projects/{project_ref}/allowance/reductions`
  (`reduce_project_allowance`) takes an amount off a project's allowance, for
  example when you refund your client. It needs a company-level key, and
  `reference` makes it safe to retry exactly like a top-up. A reduction can't
  take the project's total granted below zero (`409 conflict`); it can take
  what remains below zero, which refuses the project's next runs until it is
  topped up while runs in progress finish. Entries in the
  `get_project_allowance` `top_ups` log carry `kind` (`top_up` or
  `reduction`), a reduction's `amount_usd` is negative, and `granted_usd` is
  top-ups less reductions. References are unique per project across both
  kinds (`409 conflict` on reuse). Top-ups and reductions must be at least one
  cent (`422 invalid_request` below that).
- **Company limits and new-project defaults:** `GET`/`PUT /v1/limits`.
- **Per-project charges:** `GET /v1/projects/{project_ref}/charges` lists the
  same entries, ids, fields and signs as `GET /v1/charges` filtered to that
  project.
- **Default brand per project:** projects have an optional
  `default_brand_profile_id`, set on `POST /v1/projects` and
  `PATCH /v1/projects/{project_ref}` and returned on every project read. A
  playbook or document that names no brand sells as the project's default
  brand before falling back to the organization's default; a brand in the
  request, or a playbook template's brand, still wins. The default must be an
  active brand of your organization (`404 brand_profile_not_found`,
  `409 brand_profile_archived`). If a project's default brand is archived
  later, its runs that name no brand fail with `409 brand_profile_archived`
  instead of using the organization default. Brands themselves stay
  company-wide.
- **Prospecting continuations** (`POST /v1/jobs/{job_id}/continuations`) work
  with a company-level key: the parent run selects the project, and the
  continuation is charged there.
- **Refusals** use the existing `429 budget_exceeded`. `error.details` gains
  `kind` (`allowance`, `min_to_start`, `day`, `month`) and `project_id`;
  allowance refusals also carry `held_usd` and `min_to_start_usd`, with
  `period` and `resets_at` null. When several limits refuse a run, `details`
  reports one, in this order: the project's allowance, the project's monthly
  then daily limit, then the company's.

### Charges, balance, limits and price estimates

- **New `GET /v1/charges`** (operation `list_charges`) returns your company's
  charge history, newest first: every run charge (`debit`) plus credit
  purchases, gifts, adjustments, refunds and refund reversals, each with a
  signed `amount_usd`, the `balance_after_usd`, and the run's `job_id`,
  `capability` and project (`project_id`, `project_slug`, `project_name`).
  Filter by `project`, `type`, `from` and `to`; page with `limit` and
  `cursor`. A company-level key sees every entry, or one project's charges
  with `project` or the `Blackpearl-Project` header; a project key sees only
  its own project's charges. Connected Claude clients get the connected
  project's charges from the new `list_charges` tool.
- **New `GET /v1/pricing-estimates`** returns the typical charge for one unit
  of each capability at your organization's own rates (`approx_usd`),
  including any data-record fee, and the range about 80% of recent runs were
  charged within (`low_usd`, `high_usd`), so you can show an up-front price
  before submitting work. It is a guide, not a quote: each run is still
  charged for the work it does. Any API key can call it; company-level keys
  need no `Blackpearl-Project` header. Connected Claude clients get the same
  figures from the new `get_pricing_estimates` tool.
- **Every money figure now shows what you were charged.** Field names and
  types are unchanged; only the values are corrected:
  - Job `usage.cost_usd` is the amount charged for the run: `0` for a failed
    run, the partial charge for a canceled run, and the full price, including
    any data-record fee, otherwise. It matches the run's debit on your
    transactions and statements.
  - `GET /v1/usage` `rollup` and `by_capability` `cost_usd`, campaign
    `total_cost_usd`, cost-metric quotas, budgets, and `budget_exceeded` /
    `quota_exceeded` error details all count charged amounts.
  - The usage-tier monthly cap (`usage_tier.monthly_cost_cap_usd` and the
    `usage_tier` refusal's `limit_usd` and `spend_usd`) counts what the
    organization is charged, matching the published ladder.
    `usage_tier.monthly_cost_cap_usd` reports the cap that is enforced: the
    tier's cap, or the organization's lifetime gifted credit when that is
    higher.
  - Token, `backend_requests` and `backend_runtime_ms` usage fields, document
    `model`, message-template `generation_model` and
    `generation_provider_requests`, and prospecting research `provider`,
    `model_version` and `provider_names` are retained for compatibility and
    return `0`, `null`, an empty list, or `pearl_engine`. Brand guideline and
    account research provenance report `pearl_engine`, so the
    `guideline_hash` of a researched brand guideline changes once.
  - New token-metric quotas can no longer be created. Existing token-metric
    quotas report `used: 0` (and `remaining` equal to the limit) in
    `GET /v1/usage` and in `quota_exceeded` details.
- **Overdraft instead of lost results.** A job whose actual charge exceeds
  the remaining prepaid balance now succeeds and returns its result; the full
  price is charged and the balance goes negative. New jobs are rejected with
  `402 insufficient_credits` until a top-up (or auto-recharge) restores a
  positive balance, and `credits.balance_usd` in `GET /v1/usage` can be
  negative. Previously the balance was consumed and the job failed with
  `insufficient_credits` and no result; jobs that already failed that way
  keep that terminal state.
- **Budgets** count what runs are charged and can be daily as well as
  monthly. A hard budget rejects new work with `429 budget_exceeded` once the
  charges in its scope reach the limit; `error.details` reports `period`
  (`day` or `month`), `spend_usd` and `limit_usd` as charged amounts, and
  `resets_at` at the next UTC midnight or month start. `budgets[]` in
  `GET /v1/usage` still lists monthly budgets only, with `spend_usd` and
  `remaining_usd` as charged amounts. Members with the `billing` role can now
  create, change and delete budgets in the console.
- When a capped usage tier refuses a run because another run is holding its
  capacity, the message says so instead of saying the monthly cap has been
  reached. Connected Claude clients' `run_prospecting` errors name the limit
  that refused the run and carry the same details as `/v1`.

### Prospecting

- A run that delivers no prospects now ends `failed` and is not charged,
  unless the agent finished a search and found no matches. Runs that were
  interrupted, whose results could not be retrieved, or where the agent
  replied without searching previously succeeded with an empty result and
  were charged.
- A run canceled before its search started (for example while waiting for
  prospecting capacity) is not charged: `usage.cost_usd` is `0`. Long runs no
  longer lose their results when they outlive the backend sign-in.
- A run returns every prospect the agent delivered, up to 100, instead of
  cutting the result at `limit`; `limit` is the number the agent is asked to
  find. Results are read from the run's full results table, so runs whose
  agent combined several searches no longer come back empty.
- Prospects include `enrichment.phone`: a number from the contact's record
  (mobile first, then a direct line), as the source provides it. It may be a
  company main line and is not verified; it is omitted when none was found,
  like `work_email`. The CSV export gains a `Phone` column, appended after
  `Outreach Draft Status` so the earlier columns keep their positions.
- `qualification.score` reflects the engine's role or company fit score when
  the result carries one; otherwise it stays `0.9` as before. Most results
  from the current engine don't carry one yet, so expect `0.9` for most
  qualified prospects. Audience snapshots filtered with `min_score` may
  therefore keep fewer members. `min_qualification_score` does not filter
  results: the engine returns every prospect it qualifies, with its score.
- Prospect fields the source fills with a placeholder (`N/A`, `-`, `--`,
  `none`, `null`, `unknown`) are treated as missing. A prospect whose email
  was a placeholder has no `work_email`, `enrichment.status` `not_found`, and
  no longer counts in the found-email totals. Contacts at one company that
  shared a placeholder email were previously collapsed into one prospect;
  each is now its own prospect, so their ids differ from earlier runs. A
  prospect whose only evidence was a placeholder has `qualification.status`
  `unknown`.
- Prospecting events (`GET /v1/prospects/{id}/events`) no longer call the
  contacts, people, emails or phone numbers found "verified" in their prose
  (`text` and `task_status` events, and the `message` of `table` and
  `complete` events): the search does not verify them.

### Responses and errors

- Responses no longer name the services behind a run. Field names and types
  are unchanged; only values are corrected:
  - The Audiences pipeline stage previously keyed `worldwide` is reported as
    `retrieval` ("Audience retrieval") in job `stages`, campaign cycles and the
    connector tools.
  - `GET /v1/prospects/{job_id}/events` returns only documented fields for
    every event type: `text` and `task_status` text with internal service
    names replaced, `lead` events with `company_name`, `domain` and contact
    names and titles, `error` events with a fixed `message`, and no data on
    `code` and `playbook_started` events.
  - Document `progress` lines no longer name internal services.
  - A message-template job that fails because generation is not configured
    reports `error.code` `generation_not_configured`.
  - The `usage_tier` refusal of an organization that is not on a usage-billed
    plan reports what it was charged in `spend_usd` and `reserved_usd`.
- Brand guideline sources (`research.sources[].url` and the Markdown rendering
  of `GET /v1/brands/{brand_id}/guideline`) no longer carry `utm_*` tracking
  parameters, which the research tool added to the pages it cited. A
  guideline stored with them is served without them, so its `guideline_hash`
  changes once.
- Every timestamp in API responses is explicitly UTC: ISO-8601 ending in `Z`
  (for example `2026-10-08T07:43:12.508000Z`). Some fields, including the job
  `created_at`/`started_at`/`finished_at`/`expires_at` and `/v1/usage`
  `period_start`/`period_end`, previously omitted the `Z` although they were
  already UTC. Values are unchanged; parsers that accept ISO-8601 need no
  change.
- A request to an unknown `/v1` path, or with a method the path doesn't
  support, returns the standard error envelope (`404 not_found`, or `405`
  with `invalid_request`, each with a `request_id`) instead of a bare
  `{"detail": …}` body.
- Requests refused while resolving the project count against the key's rate
  limit and carry the `RateLimit-*` headers, like every other authenticated
  request.
- The Postman collection in the integration kit carries an optional, disabled
  `Blackpearl-Project` header and a `blackpearlProject` variable for use with
  company-level keys.

## Before 2026-10-10

- Playbooks can be shared publicly: `POST /v1/playbooks/{job_id}/share` returns
  a password-protected `url` (`?pw=` included), the `password` on its own, and
  `created_at` for the branded, rendered playbook, which viewers open without
  signing in (the page prompts for the password when `pw` is omitted; pages
  are never indexed); it is idempotent until revoked with
  `DELETE /v1/playbooks/{job_id}/share`. Links survive the job's 30-day
  result retention. Requires a rendered document
  (`404 playbooks_document_unavailable` otherwise). The connector adds a
  `share_playbook` tool.

- Prospecting runs one way: every `POST /v1/prospects` run (and the
  connector's `run_prospecting` tool) uses the prospect agent, which plans the
  search, streams its progress, and curates results. The `mode` field is
  deprecated and ignored — `turbo` and `agentic` are still accepted, and
  other values are still rejected — and no longer defaults to `turbo`; the
  connector tool drops its `mode` argument. Full agent runs typically take
  several minutes and return more prospects than the former turbo preview.
  Result, event and error shapes are unchanged.

- Infinite Intent adds the `coastal-retreat` programme: `create_infinite_intent`
  accepts `scenario: "coastal-retreat"` plus an optional `audience_file` summary
  (`filename`, `hashed_email_count`) echoed in progress milestones. The job
  response's `estimated_duration_seconds`, `result.filename` and
  `result.lead_count` are now per-programme values instead of World of
  Claudecraft constants (277 s / `claudecraft-leads.html` / 1267); the
  coastal-retreat programme targets about 10 seconds. Capability discovery
  names the programmes enabled for the project. The Blackpearl custom
  connector adds a `run_infinite_intent` tool, and connector `get_job_status`/
  `get_job_results` can read Infinite Intent jobs. Existing
  `world-of-claudecraft` behavior, report access rules and billing (zero
  actual charge) are unchanged.

- Infinite Intent hosted reports now require the designated viewer's browser
  login. Other signed-in accounts receive 404; signed-out visitors sign in and
  return to the report. URLs and previously issued share tokens no longer grant
  access. `report_url_expires_at` now reflects the report's retention deadline.

- Infinite Intent now targets 277 seconds (4m 37s), with milestones spread
  across the run. Agent polling guidance allows ten minutes before pausing.

- Infinite Intent now returns a hosted `report_url` to open in a browser tab
  alongside the existing HTML export. Report-only links expire after 24 hours
  and refresh through authenticated job lookup. The preview response settles on
  the standard billing fields (`billing.actual_charge_usd`,
  `billing.credits_used`); earlier jobs and idempotent retries receive the
  updated presentation. Paid APIs, account authentication and billing ledger
  behavior remain unchanged.

- Add the project-enabled Infinite Intent preview capability: authenticated
  creation, replayable progress, cancellation and private HTML export. Existing
  job lookup adds the Infinite Intent job variant. Only enabled projects
  discover it; this programme carries no charge, and existing paid APIs are
  unchanged.


- AI-agent setup now uses a short copy-and-paste prompt backed by dedicated
  connection instructions: reuse a working key, start browser approval
  immediately, poll with private one-time key storage, then check capabilities
  and credits. Skill installation is optional and no longer self-updates.
  Guidance covers interrupted delivery, expiry, billing, and temporary Cowork
  storage. Handshake responses explicitly disable caching and reinforce private
  key delivery. Endpoint paths, request/response shapes, and authentication
  behavior are unchanged.

- Documents runs now count against the organization's usage-tier monthly cap
  exactly like every other billed run: `POST /v1/documents` takes the same
  capped-tier capacity reservation as `POST /v1/playbooks`, so on a capped
  tier a second concurrent documents run is rejected with `429
  budget_exceeded` (`details.scope: "usage_tier"`) until the in-flight run
  reaches a terminal state. Request and response shapes are unchanged.
- Repeated failed authentication attempts against `/v1` from one client
  address are now rejected with `429 rate_limit_exceeded` (with
  `Retry-After`) for the remainder of the window. Successful authentication
  is never throttled by this control.
- New organizations now start with the `feedback` (Outcomes) and
  `prospect_research` capabilities enabled, alongside the existing default
  set — matching the documented out-of-the-box promise. Existing
  organizations' entitlements are unchanged.
- OpenAPI and guide examples for `GET /v1/usage` now show a real usage tier
  (`tier_2`, rank 2, $500 monthly cap — previously a fictional `growth` tier)
  and the configured `topup_increment_usd` of `100.0` (previously `25.0`).
  No field, type, or behavior changed — examples only.
- The claude.ai MCP connector gains an `enrich_contacts` tool: up to 10
  contacts enrich synchronously with results returned in the tool call;
  larger sets (up to 1,000) run as an asynchronous batch polled via
  `get_job_status`. Identical gates, billing, and masking as
  `POST /v1/enrichments`; enrichment jobs are now also readable through the
  connector's job tools.
- Enrichment lookups are now fast for every identifier class: email- and
  LinkedIn-identified contacts resolve through the platform data service's
  indexed identity endpoints (milliseconds instead of tens of seconds per
  contact), so synchronous email/LinkedIn enrichments complete well within
  the request deadline and large batches no longer scale linearly with slow
  per-contact scans. Canonical LinkedIn URLs (`https://www.linkedin.com/in/…`)
  now match; previously only the bare `linkedin.com/in/…` form did. A
  `full_name` with a company identifier now narrows a company-tier match
  toward the named person's record. No request or response shape changed.
- Enrichment now executes (Preview): `POST /v1/enrichments` enriches 1–10
  contacts synchronously — post identifiers you hold (`email`, `linkedin_url`,
  or `full_name` plus a company) and receive values for exactly the requested
  fields in the response — and `POST /v1/enrichment-batches` runs up to 1,000
  contacts asynchronously with the same request and result shapes
  (`GET /v1/enrichment-batches/{batch_id}` or `GET /v1/jobs/{job_id}` to
  poll). Runs carry a `level`: `lookup` (a direct match against the
  platform's data) is available; `research` and `verify` return
  `enrichment_level_unavailable` until they ship on the same endpoints.
  Fields needing a higher level (`company_latest_funding`,
  `work_email_verification`, `person_seniority`) are rejected at create with
  `enrichment_fields_unsupported`, naming the fields. A contact bills one flat
  per-record data fee only when its result carries a value for at least one
  requested field — the result's `contacts_billed` reports that count;
  matches that serve no requested value, unmatched contacts, and failed runs
  bill nothing; personal emails, phone numbers, and personal locations are
  never returned. Retryable 503s from `POST /v1/enrichments` carry a
  `Retry-After` header during a deploy restart or when synchronous capacity
  is briefly saturated.
  The contract-only `/v1/enrichment-specifications` resource is retired and
  removed along with its `enrichment_*` specification error codes — the
  request is now the specification. New public error codes:
  `enrichment_level_unavailable`, `enrichment_fields_unsupported`,
  `enrichment_input_invalid`, `enrichment_backend_error`,
  `enrichment_backend_invalid_response`, `enrichment_backend_unavailable`,
  `enrichment_backend_not_configured`. Removing the duplicate class also
  renamed the OpenAPI component
  `app__data_intake_schema__RequiredConnectorCapability` to
  `RequiredConnectorCapability` — regenerate SDK clients built from
  `/v1/openapi.json` if they reference the Data Intake schemas.

- Added an authenticated MCP server at `/mcp` so the platform can be used as a
  Claude custom connector, alongside the existing public documentation MCP at
  `/docs/mcp/` (unchanged). Authorization is OAuth 2.1 owned by the gateway:
  RFC 8414/9728 discovery documents at `/.well-known/oauth-authorization-server`
  and `/.well-known/oauth-protected-resource[/mcp]`, RFC 7591 dynamic client
  registration, authorization-code grant with PKCE (S256 only), rotating
  refresh tokens, and RFC 7009 revocation, all under `/oauth/*`. Consent binds
  each connection to one organization and project; connections are listed and
  revocable under Settings → Connected apps. MCP access tokens are
  audience-bound: they are rejected by `/v1/*`, and `bp_live_` project API keys
  are rejected by `/mcp`. Connector tools mirror the `/v1` job surface (run
  playbook, run prospecting, run campaign cycle, poll job status, fetch job
  results, usage summary) and enforce the same per-organization capability,
  quota, budget, tier, and prepaid-credit gates. The `/v1` contract itself is
  unchanged.

- Connector grants do not outlive the approving user's access. Removing the
  approver from the organization (or deactivating them) revokes their
  connections — immediately on member removal, and as a backstop on the
  connection's next request. While an approver's role is reduced below
  API-key-issuance rights, the connection is blocked with an explanatory
  error and resumes if the role is restored. `POST /oauth/revoke` now also
  accepts revocation requests that omit the `client_secret` field entirely,
  as public clients legitimately do.

- `POST /v1/offers` and `POST /v1/outcomes` now enforce their capability
  entitlements (`offers` and `feedback` respectively), matching every other
  gated operation: a request for an organization without the capability fails
  with `capability_disabled` (403, not retryable). Reads are unchanged —
  `GET /v1/offers`, `GET /v1/outcomes`, and `GET /v1/outcomes/insights` stay
  available regardless of entitlement. Previously these two creation
  operations executed even when the capability was disabled.

- Usage-tier advancement is now keyed to **lifetime credit purchases** plus
  account age, not consumption. The default ladder: Free ($100/mo cap, 10 req/min) → Tier 1 ($5 purchased) → Tier 2
  ($50, 7 days) → Tier 3 ($100, 7 days) → Tier 4 ($250, 14 days) → Tier 5
  ($1,000, 30 days, $50,000/mo cap). There is no longer an earned uncapped
  tier. A landing payment refreshes the organization's tier immediately.
  Promotional credits never advance the tier, but the effective monthly cap
  now never sits below the organization's total granted promotional credit,
  so gifted credit is always consumable. `budget_exceeded` errors with
  `details.scope: "usage_tier"` report the effective cap (including the
  promotional floor) in `details.limit_usd`. See the rate-limits guide for
  the full ladder.

- `GET /v1/capabilities` now returns every generally available capability with
  an `enabled` flag instead of only enabled capabilities, so clients can
  distinguish a capability that exists but is disabled from one that does not
  exist. Capabilities that are not generally available are still returned only
  when enabled for the organization. `capability_disabled` error messages on
  `/v1` operations now direct callers to `GET /v1/capabilities`.

- Jobs can no longer hang in `running` indefinitely. A job whose worker is lost
  (for example across a platform restart) is resumed automatically when its
  backend run can be safely re-attached; otherwise it transitions to `failed`
  with a retryable error message. Every job now also has a hard runtime
  ceiling (24 hours for `audiences`, 60 minutes for other types) after which it
  transitions to `failed`. Timed-out and lost runs are never charged. Terminal
  jobs now report wall-clock `duration_ms` in `usage`.

- Playbooks gain an optional `intelligence` tier (`low` | `medium` | `high` |
  `ultra`) selecting the generation agents' model class. Settable per run on
  `POST /v1/playbooks` and as a default on org playbook templates (used by
  their one-time research too); omitted runs inherit the template's tier,
  else `high` (the previous behavior).

- Org playbook templates become brief-driven artifact templates. Creation
  needs only a name, an offer/brand binding, and one natural-language `brief`
  (plus optional uploaded supporting documents); a one-time research job then
  produces the template's artifact set — an offer research pack (markdown
  docs + sources + uploads), a per-template Jinja document template, and a
  per-template payload JSON schema with per-field authoring guidance. There
  is no approval step: research (or an artifact edit) finishing is the
  release. `POST /v1/playbooks` fails with `409 playbook_template_not_ready`
  (not retryable) only while research is still running or failed with nothing
  live yet; a refresh over a live version never blocks runs. Org template
  objects expose `template_state`
  (`ready` | `researching` | `research_failed` | `draft`), `live_version`,
  `has_artifacts`, and `brief`. Hand-written canons are live from the start;
  templates created before artifact sets keep running on their canon.
- **Breaking:** removed runtime synthetic capability modes and the corresponding
  `*_STUB` configuration switches. Playbooks, Audiences, Prospecting, Documents,
  Account Research, CRM schema discovery, Brand Research, and Message Generation
  now call only their configured integration boundary; missing configuration fails
  closed instead of returning fabricated success. Transactional email is disabled
  as a true no-op when email delivery is not configured, and card top-ups require Stripe.
- **Breaking:** removed the `_stub` response property and stub-only enum values from
  Account Coordination, Account Research, Company Dossier specifications, Data
  Intake specifications, Documents, Enrichment specifications, Message Templates,
  Professional Network specifications, Prospect Research, Prospecting,
   Qualification Policies, CRM schema snapshots, and Site Audit specifications.
   Connector verification metadata now reports `unavailable` rather than `stub` /
   `not_run`, and invoking an unsupported live verification returns `501`.
- Message Templates now supports asynchronous model-backed drafting through
  `POST /v1/message-template-revisions/generate` and evidence-bound prospect copy through
  `POST /v1/message-template-revisions/{revision_id}/prospect-message`. Both operations return a
  typed `message_templates` job, accept `Idempotency-Key`, remain approval-only, and never enqueue or
  send. Prospect results use `DRAFT_READY`, `NEEDS_INPUT`, `BLOCKED`, or `DEMONSTRATION_ONLY`; failed
  hard gates return no polished copy and make no provider request. For real recipients the platform,
  rather than the caller, verifies the operator-approved policy version, retained qualification and
  address provenance, and current Outcome-ledger suppression state. Personalization renders the
  selected immutable revision locally and validates the complete returned subject and body. Successful
  generations settle job result, revision, usage, and charge through a durable billing
  outbox.
- Added the Preview `POST /v1/site-intelligence` operation: a bounded,
  robots-respecting crawl of the target website's own HTTPS origin (crawl
  options: `max_pages`, `max_depth`, `include_paths`, `exclude_paths`,
  `focus_areas`) distilled by a platform-managed model into one typed
  site-intelligence report (company profile, products, pricing, customers,
  technology, team, content, positioning — each section grounded in crawled
  `source_urls`). The run is an asynchronous `site_intelligence` job: poll
  `GET /v1/jobs/{job_id}`, which now includes the `site_intelligence` shape in
  its typed job union. Requires the `site_intelligence` capability; admission
  is gated by the standard quota, budget, tier, and credit checks, and the
  run's charge is reported in job `usage`.
- **Breaking:** removed `GET /v1/prospecting/outcomes` and
  `POST /v1/prospecting/outcomes`. Record prospect-bound, account, and campaign
  feedback through `GET` and `POST /v1/outcomes`; there is no compatibility
  alias.
- Public stability is now classified per operation. GA operations cover
  platform core, Audiences, Brands, Offers, Campaigns, Outcomes, Playbooks,
  core Prospecting, Documents generation and download, and synchronous account
  research. Connector inventory, Prospecting continuations and qualification
  policies, Account Coordination, Company Dossier specifications, Data Intake,
  Enrichment, Message Templates, Professional Network, Prospect Research
  specifications, and Site Audit remain explicitly `x-stability: preview`.
- Added the GA Brand, Offer, Outcome, audience-snapshot, Playbook-template, and
  Prospecting event-stream operations, plus Campaign GTM-relation updates.
  Canonical guides and coverage now exist for every public operation.
- Added the Preview contract surfaces for connector inventory and the bounded
  specification resources listed above. These labels do not imply live
  provider execution; each Preview guide states its operational boundary.
- New `POST /v1/documents` generates finished sales-collateral files —
  proposals, playbooks, slide decks, GTM strategies, reports and one-pagers as
  `.pptx`/`.docx`/`.pdf` — as an asynchronous `documents` job driven by the
  managed document agent. Send a `brief` plus optional `document_type`,
  `format`, `target_domain`, `brand`, `offer`, and up to three reference
  `template_urls` the agent follows for structure and tone; the platform
  composes the selling context from the brand's Brand Pack (the brand must
  have a completed guideline — `409 brand_guideline_missing` otherwise) and
  the attached Offer (`404 offer_not_found` / `409 offer_archived` when the
  selector is stale). The typed result references the stored files; download
  bytes with the new `GET /v1/documents/{job_id}/files/{file_id}`
  (format-specific content type, attachment filename, job retention window).
  Jobs appear in `GET /v1/jobs/{job_id}` as a typed `documents` variant with
  curated agent `progress`, and real runs are charged for the work the agent
  does. The `documents`
  capability is GA and enabled for new organizations.
- New `POST /v1/account-research` returns one structured website-intelligence
  record for a company domain — identity, scale, market, digital presence
  (including `detected_tech`), buying signals and surfaced contacts —
  synchronously. Unknown domains return `404 account_not_found` unmetered, or
  send `analyze: true` to fetch and analyze the website on demand (metered as
  one extra request, result carries
  `analyzed: true`, unfetchable sites return `422 account_unanalyzable`).
  Send `include_similar: true` to enrich the result with up to 10 lookalike
  companies (`similar_companies`, with similarity scores) from the research
  backend's similarity index. The `prospect_research` capability is GA and
  enabled for new organizations; each successful lookup meters one request.
- Org playbook templates gain a reviewed offer-canon workflow. Creating a
  template without a canon triggers a one-time offer research job; the
  researched canon must be reviewed and approved (in the console) before the
  template can run. While the canon is researching, awaiting review, or its
  research failed, `POST /v1/playbooks` fails with
  `409 playbook_template_not_approved` (not retryable — approve or edit the
  template's canon first). Approved canons are reused verbatim by every run;
  the seller is never re-researched per prospect. Org template objects in
  `GET /v1/playbook-templates` now include `review_status`
  (`approved` | `pending_review` | `researching` | `research_failed` | `draft`),
  `approved_version`, `pending_version_id`, `research_job_id`,
  `research_job_status`, and `research_error`. Templates created with a
  hand-written canon are approved from the start; existing templates with a
  canon were grandfathered as approved.
- `GET /v1/playbooks/{job_id}/document` now serves the platform-persisted copy
  of the rendered document; the generation backend is only proxied for jobs
  that predate artifact persistence. No response shape change.
- Playbook templates are now organization-defined. `playbook_template_key`
  accepts any org template key (created in the console) in addition to the
  curated catalog; unknown keys fail at run time with
  `playbook_template_not_found` instead of request validation. `stage` accepts
  any short lowercase slug — organizations define their own stage vocabulary —
  and `GET /v1/playbook-templates` now returns org templates ahead of the
  catalog with the merged stage list. An org template binds its offer and
  brand profile as defaults and forwards its focus, guidance, and offer canon
  to the generation backend.
- Playbooks results gain an optional `document_url` field: when the generation
  backend produced a fully rendered playbook document, `result.document_url`
  is non-null and the document can be fetched with the new
  `GET /v1/playbooks/{job_id}/document` operation (returns `text/html`;
  `404 playbooks_document_unavailable` when the job has no rendered document,
  `409 job_not_finished` before the job succeeds).
- Playbooks generation now forwards the resolved offer substance, stage
  template guidance, campaign frame, and requested sections to the generation
  backend, so backend offer templates can bind to platform Offers. No public
  request fields changed.
- `POST /v1/prospects` accepts a typed `mode` (`turbo` or `agentic`, default
  `turbo`). `turbo` streams the deterministic database-search pipeline —
  fastest to first prospect. `agentic` engages the prospect agent, which
  plans the search, streams status updates, reasoning, and searches into the
  run's live thread (`GET /v1/prospects/{job_id}/events`), and delivers a
  curated prospect table. Agentic runs are charged for the work the agent
  does. When the agentic backend is unreachable the job fails
  with a clear error instead of returning fabricated results. The unreleased
  free-form `search_mode` input field was replaced by `mode`.
- Prospecting results now carry provider-derived qualification scores,
  validated-email confidence, and company firmographics (industry, headcount,
  location) when the backend supplies them.
- `GET /v1/usage` now returns a nullable `usage_tier` object (`key`, `name`,
  `rank`, `rate_limit_per_minute`, `monthly_cost_cap_usd`) and the
  `rate_limit.limit` value is now resolved from the organization's usage tier
  instead of a single global constant. Tiers grow automatically with
  cumulative paid usage and account age. Job creation adds a tier-based
  monthly spend cap to the existing admission gates: when the cap is reached,
  requests fail `429 budget_exceeded` with `error.details.scope` set to
  `"usage_tier"` (alongside `tier`, `limit_usd`, `spend_usd`, `resets_at`).
  As with budgets, do not retry until `resets_at` or the organization's tier
  changes.
- Audience cycles that run with `playbooks_enabled` now also register each
  generated playbook as a succeeded `playbooks` job in the same project,
  linked to the campaign via `campaign_id`. These appear in `GET /v1/jobs`
  and job listings alongside directly created playbooks; they do not consume
  playbook quota or record additional cost (the spend belongs to the cycle).
  Candidate `playbook_url` values no longer embed an access password;
  playbook access goes through the authenticated playbook endpoints.
- Audience runs now scale the entire backend pipeline (candidate retrieval,
  preliminary ranking, deep enrichment) to the requested `target_size` instead
  of only the final audience size. Small audiences complete faster and record
  proportionally lower cost; results for a given `target_size` are unchanged.
- `max_contacts_per_company` values up to the documented maximum of 10 are now
  honored; previously values above 5 were silently reduced to 5.
- Audience runs that fail, are canceled, or time out now record the work
  actually done before the terminal state. Failed and timed-out runs are
  still never charged.
- Public jobs now include `expires_at` and retain their input, result, and
  diagnostics for 30 days. Owned reads after expiry return `410 job_expired`;
  accounting and audit ledgers remain after payload cleanup.
- Authenticated responses now publish `RateLimit-Limit`,
  `RateLimit-Remaining`, and `RateLimit-Reset`. `GET /v1/usage` adds monthly
  boundaries, the rate policy, and applicable quota and budget counters.
  Accepted generation adds one usage request; completion adds its charge
  without double-counting the request.
- Quota and budget `429` errors now include scope, current/remaining values, and
  the next UTC monthly reset in `error.details`. Cost quotas now reconcile to
  `cost_usd` usage correctly.
- Every public OpenAPI operation now carries an `x-stability` label. The public
  compatibility, preview, deprecation, and support-window policy is documented
  in [API compatibility and deprecation](https://engine.neraperla.com/docs/versioning).
- Public Playbooks, standalone Audience, and campaign-cycle job creation now
  accept `Idempotency-Key`. Keys are scoped to the authenticated project and
  operation; matching input replays the original response for 24 hours, while
  changed input returns `idempotency_key_reused`. Concurrent matching requests
  cannot create duplicate jobs and may transiently return
  `idempotency_in_progress` until the original response is stored.
- **Breaking (OpenAPI)**: public operations now use one HTTP Bearer security
  scheme instead of an optional per-operation `authorization` header parameter.
  Generated clients should configure the project API key once as a Bearer
  credential.
- **Breaking (typed jobs)**: `POST /v1/playbooks` now returns a
  Playbooks-specific typed job response, and `GET /v1/jobs/{job_id}` is a
  `type`-discriminated Playbooks-or-Audiences union. Stable public inputs,
  results, usage, candidates, campaigns, and usage rollups are now explicit
  schemas rather than free-form JSON objects.
- Public API errors now use a finite documented code catalog. Retry decisions are
  made by `error.code`: `rate_limit_exceeded` includes `Retry-After` and is
  transient, while `quota_exceeded` and `budget_exceeded` must be resolved by a
  reset or configuration change. Unexpected `/v1` failures return the same
  request-ID-bearing `ErrorResponse` envelope and documented 5xx responses.
- Added **Campaigns**: `POST /v1/campaigns` saves an audience-targeting campaign,
  `GET /v1/campaigns` / `GET /v1/campaigns/{campaign_id}` list and read them, and
  `POST /v1/campaigns/{campaign_id}/cycles` runs a campaign (a "cycle"), returning a
  standard job. `GET /v1/campaigns/{campaign_id}/cycles` lists a campaign's runs.
  Setup artifacts from the first cycle are reused, so later cycles skip the setup
  stages. Campaign creation supports a stable project-scoped `key`; cycle creation
  supports the standard `Idempotency-Key` header.
- **Breaking (audiences)**: a succeeded audiences job's `result` is now a compact
  summary (`count`, `result_shape`, score stats, `top_industries`, `icp`) and no
  longer embeds `candidates`. Fetch candidates from
  `GET /v1/audiences/{job_id}/candidates`, which now supports `q`, `sort`
  (`final_score`, `deep_match_score`, `company_name`, `full_name`), `direction` and
  cursor pagination over the full candidate set (no 500-row storage cap).
- `POST /v1/audiences` now creates a campaign and starts its first cycle; the
  returned job (and all jobs) includes a `campaign_id` field. Job `stages` entries
  are now a typed object (`key`, `label`, `status`).
- Removed capability-specific admission prices and all configured pre-run credit reserves.
  Usage-billed organizations may start work with any positive spendable balance. The run's
  price is charged at settlement; when it exceeds the remaining balance, that balance
  is consumed and the asynchronous job fails with `insufficient_credits` without exposing its
  result. Auto-recharge continues to trigger from the resulting low balance.
- `GET /v1/usage` now returns a typed response including a `credits` object
  (`billing_enabled`, `balance_usd`, `topup_increment_usd`).

- OpenAPI `servers` and the `docs_url` in error responses now come from the
  gateway's `PUBLIC_API_BASE_URL` and `PUBLIC_DOCS_BASE_URL` settings instead of
  hard-coded hosts. Local development defaults to `http://localhost:8400` and
  `http://localhost:5173/docs`.
- API keys are issued in one standard type (`bp_live_` prefix). The console no
  longer offers a test/live mode selector, and a key prefix never changes
  execution semantics: every hosted call performs real work and records real
  usage. Existing keys, including legacy `bp_test_`-prefixed ones, continue to
  authenticate unchanged. Use separate development, staging, and production
  projects for isolation.

- Candidate playbook generation in the audiences pipeline is **disabled
  platform-wide** while the upstream playbook pipeline is reworked. The
  `playbooks_enabled` request flag on audience and campaign creation is still
  accepted and recorded with the job for compatibility, but no cycle generates
  playbooks and no playbook jobs are registered from cycle results. Existing
  cycle-generated playbooks remain viewable. Directly created playbooks
  (`POST /v1/playbooks`) are unaffected.

- New CSV exports. `GET /v1/prospects/{job_id}/export.csv` downloads every
  prospect of a succeeded prospecting run; its fourteen columns and value
  formatting mirror the prospecting run table in the web console (percentages,
  merged Industry / Location, evidence insight, and outreach draft status
  copy). `GET /v1/audiences/{job_id}/candidates.csv` downloads the full
  candidate list behind `GET /v1/audiences/{job_id}/candidates`, one row per
  contact with company columns repeated. Both are UTF-8 RFC 4180 with CRLF
  line endings, deterministic row order, and spreadsheet-formula
  neutralization, and both return `not_ready` until the job has succeeded.
  The web console adds a matching Export CSV button to the prospecting run
  page. The existing console audience-candidates CSV download now shares the
  same row builder and gains the formula neutralization; as part of this,
  boolean cells (for example `is_primary`) are rendered lowercase (`true` /
  `false`) where they were previously `True` / `False`.
