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_idandtemplate_idon 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 /brandsand pass itsbrand_idon a job. - Template. The layout: sections and call to action. Make one with
POST /templates(built-in sections, a call to action, optionally abrand_id), list them withGET /templates, and passtemplate_idon a job. Custom blocks, proof, pricing and the visual editor are in the app (edit_urlon 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_) andtemplate(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
typeislanding_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: 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: trueand costs nothing. A failed one is tried again and charged again. - Per job, optional. Send an
Idempotency-Keyheader (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 is409 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 for what every action costs, when credits are refunded and every limit.