# Concepts

> Workspaces, brands, templates, jobs and assets, and how waiting, retries, credits and limits work.

- **Workspace.** The client the key belongs to. Its company description is what every page says about "us". Keep one workspace per client.
- **Brand = look; template = layout.** A brand is the logo, colours and fonts. A template is the sections and call to action. Pass optional `brand_id` and `template_id` on a job; the job's brand overrides the template's own brand.
- **Brand.** The look: logo, colours and fonts. Make one from a website with `POST /brands` and pass its `brand_id` on a job.
- **Template.** The layout: sections and call to action. Make one with `POST /templates` (built-in sections, a call to action, optionally a `brand_id`), list them with `GET /templates`, and pass `template_id` on a job. Custom blocks, proof, pricing and the visual editor are in the app (`edit_url` on each template).
- **App and API.** In the NeuroPage app, a template owns its look (there is no separate Brand profiles page any more). The API keeps `brand` (`brd_`) and `template` (`tpl_`) separate, so you can reuse one look across layouts or change it per job.
- **Job.** One request to make assets, or to read a brand from a website. Jobs are asynchronous.
- **Asset.** One thing made for one lead. Today the only `type` is `landing_page`: a hosted page at a permanent URL that does not expire.

### Waiting for results

Every job and asset has a `status`. Call `GET /jobs/{id}?wait=50` or `GET /assets/{id}?wait=50`: the call returns early when anything changes. Between calls, wait `poll_after_seconds`. Never start a job again to check on it. To be told instead of asking, see [Webhooks](https://docs.neuropage.io/webhooks): they are set up in the app, not through the API.

Job statuses: `running`, `completed`, `completed_with_errors`, `failed`. Asset statuses: `queued`, `processing`, `ready`, `failed`, `canceled`.

### Sending the same thing twice

- **Per lead, always.** A LinkedIn URL that already has a page in the same campaign (queued, processing or ready) comes back as `reused: true` and costs nothing. A failed one is tried again and charged again.
- **Per job, optional.** Send an `Idempotency-Key` header (MCP: `idempotency_key`). The same key within 24 hours returns the first job with status 200 instead of starting a new one. Reusing the key for a different request is `409 idempotency_conflict`.

### Credits

`cost_per_asset` (from `GET /workspace` or the template) is the most one new page costs. A lead whose LinkedIn profile NeuroPage has already read costs only the page, and a reused page costs nothing. A job is quoted lead by lead before anything starts, and each page is charged exactly its quote. If the workspace has fewer credits, the job is refused with `402` and nothing is charged. Every job shows `cost.quoted`, `cost.charged`, `cost.refunded` and `credits_remaining`.

To see the quote without starting anything, send `POST /jobs` with `dry_run: true` (MCP: `dry_run` on `generate_assets`). It answers `200` with a `JobQuote`: `credits_quoted`, `leads_accepted` (new pages), `leads_reused`, `leads_rejected`, `credits_remaining` and `enough_credits`. No job, no charge.

In a campaign that runs research columns, a new lead's quote includes them. Research is charged when it runs, a minute or so after the job starts, and a column that finds nothing is refunded then. Pages that fail later are refunded too: `GET /jobs/{id}` shows it in `refunded`, `credits_refunded` and `refund_message`.

### Limits

| Limit | Value | Error |
|---|---|---|
| Requests per key (or per signed-in user) | 60 per minute | `429`, `limit: requests` |
| Credits per key | The key's monthly cap, if set | `402 spend_cap_reached` |
| Leads per job | 25 | `422 too_many_leads` |
| Running page jobs per workspace | 2 | `429`, `limit: running_jobs` |
| New pages per workspace | 200 per hour, 1,000 per day | `429`, `limit: assets_hour` or `assets_day` |

Every `429` has a `Retry-After` header. Every response after the key is checked also carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds), so a client can slow down before it is refused. Credits are the hard limit on spend.

### Accepted, then started

`POST /jobs` charges and starts every page before it answers, usually in a few seconds. A page that cannot start shows up in `rejected` with `temporarily_unavailable` (or `insufficient_credits`), and anything it was charged is refunded before the answer: the same response says so in `refunded: true`, `credits_refunded` (also per lead in `rejected[].credits_refunded`) and `refund_message`.

A LinkedIn URL must be a personal `linkedin.com/in/` profile. Anything else (a company page, a post, a search, an old `linkedin.com/pub/` address) is rejected before anything is charged: in `rejected` with `invalid_linkedin_url`, or as `422 validation_failed` when no lead in the job is valid.

### Ids

Ids have a prefix that says what they are: `brd_` brand, `tpl_` template, `cmp_` campaign, `job_` job, `ast_` asset. An id from another workspace is a `404`, the same as an id that does not exist.

See [Credits and limits](https://docs.neuropage.io/credits-and-limits) for what every action costs, when credits are refunded and every limit.
