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: 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

LimitValueError
Requests per key (or per signed-in user)60 per minute429, limit: requests
Credits per keyThe key's monthly cap, if set402 spend_cap_reached
Leads per job25422 too_many_leads
Running page jobs per workspace2429, limit: running_jobs
New pages per workspace200 per hour, 1,000 per day429, 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.