# NeuroPage API

> Personalized outbound landing pages for B2B leads, from a LinkedIn URL.

NeuroPage makes a personalized outbound landing page for every B2B lead you give it, from nothing more than their LinkedIn profile URL. Each page is written about that lead's company and role, styled in your brand, and hosted at a permanent URL you can paste into Instantly, HeyReach, Lemlist or any sequence. Afterwards you can see who opened their page, how far they scrolled, and who clicked or booked.

You can use it two ways: from an AI agent such as claude.ai, Claude Code, Claude Desktop or Cursor through our MCP server, or from code and tools like Clay, n8n and Make through this REST API. Agents can sign in with your NeuroPage account or use an API key; the REST API uses an API key. Both use the same objects.

**Fastest start, claude.ai:** in claude.ai, open **Settings, Connectors, Add custom connector**, paste `https://neuropage.io/api/mcp` and sign in with your NeuroPage account. No key needed. Details under claude.ai and Claude Desktop below.

## 1. Get your API key

1. Open the app and go to **Settings, API & MCP** (`https://neuropage.io/home/{workspace}/settings/api`).
2. Click **Create key**, give it a name, and copy the key. It starts with `np_live_` and is shown once.

Good to know:

- One key belongs to one workspace, and one workspace is one client. An agency makes one key per client workspace.
- Workspaces are created in the app at `https://neuropage.io/home`. Signed in to the MCP server with your NeuroPage account (OAuth), an agent can also create one with `create_workspace`.
- Reading works on any workspace. Changing anything (creating or editing brands, generating pages) needs a paid plan or a trial with a card on file; without one those calls return `403 plan_required` with the billing link, and `GET /workspace` shows it in `plan`.
- Treat the key like a password. Anyone with it can spend the workspace's credits.
- Give a key a monthly credit cap when you create it (or later). A job that would pass the cap is refused with `402 spend_cap_reached`.

## 2. Connect your AI agent

The MCP server is at `https://neuropage.io/api/mcp` (Streamable HTTP). Sign in with your NeuroPage account (OAuth), or send an API key in the `Authorization` header.

### claude.ai and Claude Desktop

1. Open **Settings, Connectors** and click **Add custom connector**.
2. Name it NeuroPage and paste `https://neuropage.io/api/mcp` as the URL.
3. Click **Connect**, sign in to NeuroPage, and click **Allow**.

The connector acts as you, in every workspace you belong to. If you are in several (an agency with a workspace per client), Claude asks which client each request is for. You can disconnect it any time under **Settings, API & MCP**.

### Claude Code

Sign in with your NeuroPage account: add the server without a key, then run `/mcp` in Claude Code and choose NeuroPage to sign in.

```bash
claude mcp add --transport http neuropage https://neuropage.io/api/mcp
```

Or use an API key, which is pinned to one workspace:

Run this once in your terminal, with your key:

```bash
claude mcp add --transport http neuropage https://neuropage.io/api/mcp --header "Authorization: Bearer np_live_YOUR_KEY"
```

To share the setup with your team without sharing the key, put this in `.mcp.json` at the root of the project and set `NEUROPAGE_API_KEY` in each person's environment:

```json
{
  "mcpServers": {
    "neuropage": {
      "type": "http",
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NEUROPAGE_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop with an API key

If you prefer a key to signing in, open **Settings, Developer, Edit Config** and add NeuroPage to `claude_desktop_config.json`, then restart Claude Desktop. This needs Node.js on your computer, because `mcp-remote` runs through `npx`.

```json
{
  "mcpServers": {
    "neuropage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://neuropage.io/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer np_live_YOUR_KEY"
      }
    }
  }
}
```

The header is written as `Authorization:${AUTH_HEADER}` with no space on purpose: Claude Desktop on Windows splits arguments on spaces, so the space lives in the `env` value instead.

### ChatGPT

Custom connectors in the ChatGPT app need Developer mode, which depends on your ChatGPT plan and workspace settings, and the menu names can change:

1. In ChatGPT, open **Settings**, find **Apps & Connectors**, and turn on **Developer mode** under the advanced settings.
2. Create a connector named NeuroPage with `https://neuropage.io/api/mcp` as the MCP server URL.
3. Choose **OAuth** as the authentication, sign in to NeuroPage, and click **Allow**.

The connector acts as you, like the claude.ai connector. No API key is needed.

### OpenAI API

In the Responses API, add NeuroPage as a remote MCP tool and send your key in `headers`. Here the read tools run on their own and anything that writes or spends credits comes back as an approval request first:

```js
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5",
  tools: [
    {
      type: "mcp",
      server_label: "neuropage",
      server_url: "https://neuropage.io/api/mcp",
      headers: { Authorization: "Bearer np_live_YOUR_KEY" },
      // Reads run on their own; anything that writes or spends credits
      // comes back as an approval request first.
      require_approval: { never: { tool_names: ["list_workspaces", "get_workspace", "list_brands", "get_brand", "list_templates", "get_template", "get_job", "list_assets", "get_asset_stats", "get_company_profile", "list_media", "list_campaigns", "list_event_subscriptions", "get_campaign", "list_leads", "list_columns", "check_variables", "list_instantly_campaigns"] } },
    },
  ],
  input: "Check my NeuroPage workspace and tell me what is missing.",
});

console.log(response.output_text);
```

For Codex, OpenAI's coding agent, keep the key in an environment variable:

```bash
export NEUROPAGE_API_KEY=np_live_YOUR_KEY
codex mcp add neuropage --url https://neuropage.io/api/mcp --bearer-token-env-var NEUROPAGE_API_KEY
```

### Cursor

[Add NeuroPage to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=neuropage&config=eyJ1cmwiOiJodHRwczovL25ldXJvcGFnZS5pby9hcGkvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIG5wX2xpdmVfWU9VUl9LRVkifX0%3D). After it opens, replace `np_live_YOUR_KEY` with your key in Cursor's MCP settings.

Or add it to `~/.cursor/mcp.json` yourself:

```json
{
  "mcpServers": {
    "neuropage": {
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer np_live_YOUR_KEY"
      }
    }
  }
}
```

### Grok

The Grok command-line tool adds the server the same way as Claude Code. Run this once, with your key:

```bash
grok mcp add --transport http neuropage https://neuropage.io/api/mcp --header "Authorization: Bearer np_live_YOUR_KEY"
```

### VS Code

Add this to `.vscode/mcp.json`. VS Code asks for the key once and stores it securely.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "neuropage-key",
      "description": "NeuroPage API key",
      "password": true
    }
  ],
  "servers": {
    "neuropage": {
      "type": "http",
      "url": "https://neuropage.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:neuropage-key}"
      }
    }
  }
}
```

### Clay, n8n, Make and scripts

Use the REST API below with the header `Authorization: Bearer np_live_YOUR_KEY`.

## 3. Try it

Ask your agent, in this order:

1. "Set up a NeuroPage brand from acme.com and show me the logo and colours it found."
2. "Make NeuroPage landing pages for these 3 LinkedIn profiles with that brand: <3 profile URLs>."
3. "Which of those leads have viewed their page?"

The agent checks your workspace, tells you what the pages will cost before it spends anything, waits for the pages, and gives you a table of leads and page URLs.

## REST quickstart

Check the key and see your credits, brands and templates:

```bash
curl https://neuropage.io/api/v1/workspace -H "Authorization: Bearer np_live_YOUR_KEY"
```

Make pages for 3 leads. Only `linkedin_url` is required; a name and company make nicer page URLs.

```bash
curl -X POST https://neuropage.io/api/v1/jobs \
  -H "Authorization: Bearer np_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-job" \
  -d '{
    "type": "landing_page",
    "leads": [
      { "linkedin_url": "https://www.linkedin.com/in/jane-doe", "first_name": "Jane", "last_name": "Doe", "company": "Acme", "external_ref": "row-1" },
      { "linkedin_url": "https://www.linkedin.com/in/john-roe", "external_ref": "row-2" },
      { "linkedin_url": "https://www.linkedin.com/in/ana-lima", "external_ref": "row-3" }
    ]
  }'
```

The answer is a job with status `running`. Wait for it (the call returns as soon as something changes, or after 50 seconds):

```bash
curl "https://neuropage.io/api/v1/jobs/job_...?wait=50" -H "Authorization: Bearer np_live_YOUR_KEY"
```

When the status is `completed`, list the pages:

```bash
curl "https://neuropage.io/api/v1/assets?job_id=job_..." -H "Authorization: Bearer np_live_YOUR_KEY"
```

A few pages take about 1.5 to 3 minutes. 25 take longer.

## Concepts

- **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 below: 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.

### Errors

Errors are `application/problem+json` with a stable `code`, a human `detail`, a `request_id`, and when there is one, a `hint` (the next step, in one sentence) and a `fix` (`{ "url" }` to show the user, or `{ "tool" }` to call). Every response has a `Request-Id` header.

The `type` is `https://neuropage.io/about/documentation/api#<code>`, which opens that code's entry below.

#### invalid_request

**400.** The body is not valid JSON, or the asset type is unknown. **What to do:** Fix the request. Sending it again unchanged fails again.

#### unauthorized

**401.** The API key is missing, unknown or revoked. **What to do:** Send Authorization: Bearer np_live_... with a key from Settings, API & MCP.

#### insufficient_credits

**402.** The workspace has fewer credits than the job costs. Nothing was charged. **What to do:** Add credits at fix.url, or send fewer leads.

#### spend_cap_reached

**402.** The job would take this API key past its monthly credit cap. Nothing was charged. **What to do:** Send fewer leads, or ask a workspace owner to raise the cap at fix.url. Caps reset on the 1st (UTC).

#### plan_required

**403.** A write (any method but GET, or an MCP tool that creates or changes something) on a workspace with no paid plan or trial with a card. Reads still work. **What to do:** Show the user fix.url and stop writing. GET /workspace shows the same state in plan.

#### not_found

**404.** The id is unknown, malformed, or belongs to another workspace. Over MCP with OAuth: the workspace slug is not yours, or you are in no workspace yet. **What to do:** Use an id this workspace returned. No workspace yet: create one (fix.url, or create_workspace over MCP).

#### campaign_not_eligible

**409.** The campaign_id is not active with automatic page generation on. **What to do:** Leave out campaign_id, or fix the campaign at fix.url.

#### idempotency_conflict

**409.** The Idempotency-Key was used in the last 24 hours for a different request. **What to do:** Use a new key for a new request. Send the exact same request to get the first job back.

#### brand_not_ready

**409.** The brand is still being read from its website. **What to do:** Wait for the brand job with GET /jobs/{id}, then send the request again.

#### template_not_usable

**409.** The template call to action has no destination. **What to do:** Show the user fix.url to finish the template in the app.

#### validation_failed

**422.** A field is invalid, or every lead was rejected. errors[] lists each field. **What to do:** Fix the listed fields and send again.

#### too_many_leads

**422.** More than 25 leads in one job. **What to do:** Split the leads into jobs of 25 and send them one at a time.

#### rate_limited

**429.** A limit was reached. The limit field says which one. **What to do:** Wait the Retry-After seconds, then send the same request again.

#### internal_error

**500.** A bug on our side. It is logged with the request_id. **What to do:** Retry once. If it repeats, contact support with the request_id.

#### temporarily_unavailable

**503.** The API is switched off, or a page could not be started. Any charge was refunded. **What to do:** Wait the Retry-After seconds and send the same request again.

## Webhooks

NeuroPage can `POST` to your URL when a landing page is hosted (`page.ready`), when an API or MCP job fails with no ready pages (`job.failed`), when a campaign sends a ready lead (`lead.ready`), and when the lead views the page, clicks, fills in the form or books a meeting.

**There is no REST `/webhooks` endpoint.** Subscriptions are created in two ways:

1. **MCP.** `subscribe_events` registers an `https` callback (defaults to `page.ready` and `job.failed`) and returns a `signing_secret` once. `list_event_subscriptions` and `unsubscribe_events` manage those subscriptions. Writes need a live plan, like other MCP writes.
2. **The app.** Open **Integrations, Webhooks** (`https://neuropage.io/home/{workspace}/integrations`) to add a webhook for `lead.ready` or landing-page activity. Those webhooks are not listed or removed through MCP.

You can still **poll**: `GET /jobs/{id}?wait=50` (MCP: `get_job`) returns as soon as anything changes, and is how to read the pages themselves.

`page.ready` and `job.failed` fire for every campaign in the workspace, including the API campaign, with no Send-stage setup. Activity events (`page.viewed`, `cta.clicked`, `form.submitted`, `meeting.booked`) do the same. `lead.ready` still needs a campaign whose **Autopilot, Send** stage uses the webhook.

### Set one up

1. Open **Integrations, Webhooks** in the app (`https://neuropage.io/home/{workspace}/integrations`) and add a webhook: a name, an `https` URL, the events it takes, and optionally an auth header (name and value). The URL and header value are stored encrypted.
2. Click **Send test** to post a sample of each event, and **Activity** to see every delivery: the body sent, your status code and the first 500 characters of your answer.
3. For `lead.ready`: open the campaign, then **Autopilot, Send**. Pick **Webhook** as the tool, pick the webhook, and arm the stage. The campaign must be active with automatic page generation on before the API can add leads to it (`409 campaign_not_eligible` otherwise).

### Events

- **`lead.ready`.** A lead's page is ready and its campaign sends the lead to this webhook: the campaign's **Autopilot, Send** stage uses the tool **Webhook** with this webhook picked, and the stage is armed. NeuroPage first waits for everything the stage requires (the page, and email or LinkedIn messages when picked). A manual send from the campaign sends it too. Once per lead: a lead already sent is skipped unless you send it again from the campaign. A paused campaign sends nothing.
- **`page.ready`.** A lead's landing page is hosted and has a permanent URL. Every campaign in the workspace, including pages made through the API or MCP. No Send-stage setup is required. Sent once per lead; a later successful delivery is not repeated.
- **`job.failed`.** An API or MCP asset job ended with no ready pages (every accepted lead failed or was canceled). Not sent when the job is completed_with_errors. Sent once per job. The body is job-level: `job_id`, `error`, `failed_lead_ids`. Brand-from-website jobs are not included yet.
- **`page.viewed`.** The lead starts a new visit to their page. Your own previews from the app do not count. Every campaign in the workspace, the API campaign included.
- **`cta.clicked`.** The lead clicks the page's call to action. Every campaign in the workspace.
- **`form.submitted`.** The lead submits the form on their page. Carries `visitor_name` and `visitor_email` when given. Every campaign in the workspace.
- **`meeting.booked`.** The lead books a meeting through the Calendly or Cal.com embed on their page. Carries `provider` and `scheduled_at`. Every campaign in the workspace.

The payloads are under **Webhook events** in this reference (`webhooks` in `openapi.json`).

### Payload

One flat JSON object, so Clay, Zapier and Make map each key to a column. Every event has `event`, `sent_at`, `lead_id`, `campaign_id`, `campaign_name`, the contact (`first_name`, `last_name`, `email`, `linkedin_url`, `company`, `job_title`, `company_domain`), `page_url` and `source_fields`. `lead.ready` adds the messages the campaign wrote: `email_subject_step_N`, `email_opening_step_N`, `email_body_step_N`, `li_connection_note`, `li_message_N`. Empty steps are left out.

`lead_id` and `campaign_id` are uuids. The API ids are the same uuids with a prefix and no dashes: `ast_` + `lead_id` is the asset, `cmp_` + `campaign_id` is the campaign. To match a webhook to the row you sent, use that asset id or `linkedin_url`; `external_ref` is not in the webhook (it stays on the job's assets).

### Delivery, auth and retries

- **Request.** NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed.
- **Auth.** Requests are not signed (no HMAC). To make sure a request is from NeuroPage, set an auth header on the webhook (for example `Authorization: Bearer <a long random secret>`) and check it in your receiver. Use `https` only; private, loopback and link-local addresses are refused, when the webhook is saved and again before every delivery.
- **Retries.** For `lead.ready`, a timeout, network error, `408`, `429` or `5xx` puts the send back on NeuroPage's job queue. The queue retries about every 30 seconds, but a lead's send is locked for 2 minutes after each attempt, so expect one or two more real attempts within a few minutes, not a long schedule. Any other answer (`4xx`, a redirect) is final. Activity events are sent once and not retried.
- **After a failure.** The campaign shows the lead's send as failed; send it again from the campaign. Webhooks are best effort: if you need every page, also poll the job or list the campaign's assets (`GET /assets?campaign_id=cmp_...`).
- **Order and duplicates.** Events are not ordered, and a retry can repeat one. Key your receiver on `lead_id` plus `event`.

### Example: what your receiver gets

This is the request NeuroPage sends for `lead.ready` (the **Send test** sample), as curl, so you can point it at your own endpoint to test it:

```bash
curl -X POST https://your-receiver.example.com/neuropage \
  -H "Content-Type: application/json" \
  -H "User-Agent: NeuroPage-Webhooks/1.0" \
  -H "Authorization: Bearer <the auth header value you set>" \
  -d '{"event":"lead.ready","sent_at":"2026-01-01T00:00:00.000Z","lead_id":"00000000-0000-0000-0000-000000000000","campaign_id":"00000000-0000-0000-0000-000000000000","campaign_name":"Test campaign","first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","company":"Analytical Engines","job_title":"Head of Growth","company_domain":"example.com","page_url":"https://pages.neuropage.io/example/ada-lovelace","email_subject_step_1":"A page we made for Analytical Engines","email_opening_step_1":"Ada, I put together a short page on how you could ...","li_connection_note":"Hi Ada, made something for you ...","li_message_1":"Here is the page I mentioned ...","source_fields":{"row_id":"r_123"}}'
```

And the job that makes such a page, sent into a campaign whose Send stage is your webhook:

```bash
curl -X POST https://neuropage.io/api/v1/jobs \
  -H "Authorization: Bearer np_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "landing_page",
    "campaign_id": "cmp_...",
    "leads": [{ "linkedin_url": "https://www.linkedin.com/in/jane-doe", "external_ref": "row-1" }]
  }'
```

### Recipe: Clay

Send rows from Clay to NeuroPage and get each page URL back in a Clay table, without polling.

1. **Receive.** In Clay, make a table with a webhook as its source and copy the webhook URL Clay gives you.
2. **Register it.** In NeuroPage, add that URL under **Integrations, Webhooks** with the event **Lead ready**. If your Clay webhook expects an auth header, put its name and value on the NeuroPage webhook. Click **Send test**: a sample row with `page_url`, `first_name`, `company`, `email_subject_step_1` and the other keys appears in Clay, one column per key.
3. **Campaign.** Make a campaign for these leads, set its **Autopilot, Send** stage to **Webhook** with that webhook, and arm it. Its API id is `cmp_` plus the uuid at the end of the campaign's URL in the app, without dashes.
4. **Send.** In the Clay table that holds your leads, add an HTTP API column: `POST https://neuropage.io/api/v1/jobs`, header `Authorization: Bearer np_live_YOUR_KEY`, body `{"type":"landing_page","campaign_id":"cmp_...","leads":[{"linkedin_url":"<LinkedIn column>","first_name":"<First name>","company":"<Company>"}]}`. One row is one lead, so one job per row.
5. **Match.** Each `lead.ready` row in the receiving table carries `linkedin_url` and `page_url`; look rows up by `linkedin_url` to bring `page_url` and the message columns back next to your leads.

Mind the limits: 25 leads per job and 2 running page jobs per workspace, so for a large table, space the requests out; a `429` has a `Retry-After` header.

## MCP tools

| Tool | What it does |
|---|---|
| `list_workspaces` | The workspaces you can use. Signed in with OAuth, pass one as `workspace` on the other tools. Call it first. |
| `create_workspace` | Signed in with OAuth only: a new workspace with you as owner. It is read-only until you start a plan in the app. Only the first workspace you create starts with 250 credits; every later one starts at 0, even if the first was deleted or handed to someone else. A workspace someone handed to you does not count as your first. At most 3 a day. |
| `get_workspace` | Credits, brands, templates, what is still missing, and how far the setup is. |
| `list_brands` | The workspace's brands. |
| `get_brand` | One brand: logo, colours, fonts. |
| `create_brand_from_website` | Create a brand (logo, colours, fonts) by reading a company website. |
| `update_brand` | Fix a brand's name, logo, colours or fonts. |
| `list_templates` | The workspace's templates (the layout), with sections, call to action, cost per page and `edit_url`. |
| `get_template` | One template: sections, call to action, its own brand, the writing instruction per section, the Settings switches and the pinned images. |
| `create_template` | Create a template (the layout) from built-in sections and a call to action, optionally linked to a brand. |
| `generate_assets` | Make a personalized landing page for each of 1 to 25 leads. `dry_run` returns the cost first. Spends credits. |
| `get_job` | A job's status and its pages, waiting up to 50 seconds for a change. |
| `list_assets` | Every page in a job or campaign. |
| `get_asset_stats` | Who viewed their page: visits, scroll depth, CTA clicks, forms, meetings. |

The tools below run a whole campaign from a chat. They are MCP only for now.

| Tool | What it does |
|---|---|
| `get_company_profile` | The company profile and tone of voice every page and message is written from. |
| `propose_company_profile_update` | Step 1 of changing them: your wording, rewritten into clear guidance, shown before and after. Saves nothing. |
| `apply_company_profile_update` | Step 2: save a proposal the user agreed to. |
| `update_template` | Change a template's name, sections, call to action, the instruction per section and the Settings switches. |
| `set_section_images` | Pin the images or video a template section shows, each with a focus point. |
| `upload_media` | Add an image or video to the library from a URL or from the bytes. |
| `create_media_upload` | A one-time upload URL for a big local file. |
| `complete_media_upload` | Record a file uploaded that way. |
| `list_media` | The workspace's library. |
| `delete_media` | Remove a file from the library. |
| `list_campaigns` | The workspace's campaigns. |
| `get_campaign` | One campaign and how far its leads are. |
| `create_campaign` | Create a campaign. `dry_run` returns every setting first, to confirm. |
| `update_campaign` | Change campaign settings. Returns what changed. |
| `import_leads` | Add up to 500 leads a call, with values for any columns. Analysis costs 1 credit a new lead. |
| `list_leads` | The lead table: status, page URL, column values, and the messages when asked. Also the export. |
| `list_columns` | A campaign's columns, and the research that can be added with its price. |
| `create_column` | Add a data, research or custom prompt column. |
| `set_cell_values` | Write values per lead and column from outside, like a CSV import. Free. |
| `run_research` | Run research columns. `dry_run` returns the cost first. Spends credits. |
| `check_variables` | Which `{{variables}}` in the template and message prompts have a column, which have none, and which columns nothing uses. |
| `generate_pages` | Build pages for leads in a campaign: 3 leads first, then all. 2 credits a page. |
| `update_message_settings` | Switch the email or LinkedIn sequence on or off and steer it. |
| `generate_messages` | NeuroPage writes the emails and LinkedIn messages. 0.5 credits a lead. |
| `set_messages` | Save emails or LinkedIn messages written by your own AI. Free. |
| `list_instantly_campaigns` | The campaigns of the workspace's Instantly account. |
| `import_from_instantly` | Pull an Instantly campaign or list into a campaign, in the background. |
| `send_to_instantly` | Add leads to an Instantly campaign with their page URL and emails. |

Every tool except `list_workspaces` and `create_workspace` takes an optional `workspace` (a slug from `list_workspaces`). With an API key it is always the key's own workspace.

The read tools (`readOnlyHint`) work on a workspace without a plan and say so in their result. The others return `plan_required` until the workspace has one.

## Sandbox

A sandbox key starts with `np_test_` and works on one shared demo workspace only, with low limits. It is for trying the API without a plan. To get one, [Contact us for sandbox access](https://neuropage.io/contact).

| Limit | Sandbox value |
|---|---|
| Requests per key | 10 per minute |
| Credits per key | 30 per month |
| New pages in the sandbox | 10 per day, 1 job at a time |

Every sandbox response carries the header `NeuroPage-Sandbox: true`, and `GET /workspace` says `sandbox: true`. Other developers use the same workspace and can see what is in it, so do not send real lead data. A sandbox key never works on your own workspace.


# Endpoints

Base URL: `https://neuropage.io/api/v1`. Every call needs `Authorization: Bearer np_live_...`. The OpenAPI document is at `https://neuropage.io/api/v1/openapi.json`.

## Workspace

Who the key acts for: credits, brands, templates, and what is missing.

### Get the workspace

`GET /workspace`

Call this first. It checks the key and returns credits, brands, templates, the cost per page, a `missing` list of what to set up before pages look right, and `plan`: whether writes are allowed. It works without a plan.

Response `200`:

```json
{
  "object": "workspace",
  "slug": "acme",
  "name": "Acme",
  "app_url": "https://neuropage.io/home/acme",
  "credits": {
    "remaining": 4970,
    "currency": "credits"
  },
  "cost_per_asset": 3,
  "company": {
    "description": "Acme builds scheduling software for field service teams.",
    "website": "https://acme.com"
  },
  "brands": [
    {
      "id": "brd_c91200b9c0034964bad543c932f2853d",
      "name": "acme.com",
      "website": "https://acme.com",
      "is_default": true
    }
  ],
  "templates": [
    {
      "id": "tpl_568c6ef294b649bebed2353fffe98920",
      "name": "Founder page"
    }
  ],
  "missing": [],
  "setup": [
    {
      "step": "company",
      "done": true,
      "tool": "get_company_profile"
    },
    {
      "step": "brand",
      "done": true,
      "tool": "create_brand_from_website"
    },
    {
      "step": "template",
      "done": true,
      "tool": "create_template"
    },
    {
      "step": "campaign",
      "done": false,
      "tool": "create_campaign"
    },
    {
      "step": "leads",
      "done": false,
      "tool": "import_leads"
    }
  ],
  "plan": {
    "active": true,
    "writes_blocked": false,
    "fix_url": null
  },
  "sandbox": false,
  "note": "One workspace is one client: all pages here describe this workspace's company."
}
```

Errors: 401, 429, 500, 503.

## Brands

The look of a page: logo, colours, fonts. Make one from a website, then fix it if needed.

### List brands

`GET /brands`

The workspace's brands: the look of a page (logo, colours, fonts). Pass one as brand_id on a job; it overrides the template's own brand.

Response `200`:

```json
{
  "object": "list",
  "data": [
    {
      "object": "brand",
      "id": "brd_c91200b9c0034964bad543c932f2853d",
      "name": "acme.com",
      "status": "ready",
      "website": "https://acme.com",
      "logo": {
        "url": "https://cdn.neuropage.io/brands/acme/logo.png",
        "dark_url": "https://cdn.neuropage.io/brands/acme/logo-dark.png"
      },
      "colors": {
        "primary": "#0F62FE",
        "background": "#FFFFFF",
        "text": "#111827",
        "heading": "#111827",
        "accent": "#F59E0B"
      },
      "fonts": {
        "heading": "Inter",
        "body": "Inter"
      },
      "is_default": true,
      "edit_url": "https://neuropage.io/home/acme/templates",
      "warnings": []
    }
  ],
  "has_more": false
}
```

Errors: 401, 429, 500, 503.

### Create a brand from a website

`POST /brands`

Reads the logo, colours and fonts from a company website. Returns at once with the brand and a job; follow the job with `GET /jobs/{id}?wait=50` until it is completed, then check the brand. When the workspace has no company description yet, it is read from the same website. Free.

Request body:

```json
{
  "website_url": "acme.com"
}
```

Response `202`:

```json
{
  "brand": {
    "object": "brand",
    "id": "brd_c91200b9c0034964bad543c932f2853d",
    "name": "acme.com",
    "status": "extracting",
    "website": "https://acme.com",
    "logo": {
      "url": null,
      "dark_url": null
    },
    "colors": {
      "primary": null,
      "background": null,
      "text": null,
      "heading": null,
      "accent": null
    },
    "fonts": {
      "heading": null,
      "body": null
    },
    "is_default": true,
    "edit_url": "https://neuropage.io/home/acme/templates",
    "warnings": []
  },
  "job": {
    "object": "job",
    "id": "job_8e2f1c0a9b7d4e6f8a1b2c3d4e5f6a7b",
    "type": "brand_from_website",
    "status": "running",
    "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
    "poll_after_seconds": 10,
    "created_at": "2026-10-27T13:30:02.114Z"
  }
}
```

Errors: 401, 403, 422, 429, 500, 503.

### Get a brand

`GET /brands/{id}`

One brand with its logo, colours and fonts.

Response `200`:

```json
{
  "object": "brand",
  "id": "brd_c91200b9c0034964bad543c932f2853d",
  "name": "acme.com",
  "status": "ready",
  "website": "https://acme.com",
  "logo": {
    "url": "https://cdn.neuropage.io/brands/acme/logo.png",
    "dark_url": "https://cdn.neuropage.io/brands/acme/logo-dark.png"
  },
  "colors": {
    "primary": "#0F62FE",
    "background": "#FFFFFF",
    "text": "#111827",
    "heading": "#111827",
    "accent": "#F59E0B"
  },
  "fonts": {
    "heading": "Inter",
    "body": "Inter"
  },
  "is_default": true,
  "edit_url": "https://neuropage.io/home/acme/templates",
  "warnings": []
}
```

Errors: 401, 404, 429, 500, 503.

### Update a brand

`PATCH /brands/{id}`

Change the name, logo, colours, fonts or default. Only the fields you send change. Problems that do not block the change come back as `warnings`.

Request body:

```json
{
  "colors": {
    "primary": "#0F62FE"
  },
  "fonts": {
    "heading": "Poppins"
  }
}
```

Response `200`:

```json
{
  "brand": {
    "object": "brand",
    "id": "brd_c91200b9c0034964bad543c932f2853d",
    "name": "acme.com",
    "status": "ready",
    "website": "https://acme.com",
    "logo": {
      "url": "https://cdn.neuropage.io/brands/acme/logo.png",
      "dark_url": "https://cdn.neuropage.io/brands/acme/logo-dark.png"
    },
    "colors": {
      "primary": "#0F62FE",
      "background": "#FFFFFF",
      "text": "#111827",
      "heading": "#111827",
      "accent": "#F59E0B"
    },
    "fonts": {
      "heading": "Inter",
      "body": "Inter"
    },
    "is_default": true,
    "edit_url": "https://neuropage.io/home/acme/templates",
    "warnings": []
  },
  "warnings": [
    {
      "field": "colors.text",
      "message": "Text on background has a contrast of 3.1:1. 4.5:1 or more reads well."
    }
  ]
}
```

Errors: 401, 403, 404, 422, 429, 500, 503.

## Templates

The layout of a page: sections and call to action. Made here or in the app, passed as template_id. Custom blocks, proof and pricing are edited in the app (each template has an edit_url).

### List templates

`GET /templates`

The workspace's templates: sections, call to action, the lead fields they use, and what one page costs. Open a template's `edit_url` to change it in the app.

Response `200`:

```json
{
  "object": "list",
  "data": [
    {
      "object": "template",
      "id": "tpl_568c6ef294b649bebed2353fffe98920",
      "name": "Founder page",
      "sections": [
        "hero",
        "problem",
        "solution",
        "howItWorks",
        "faq",
        "cta"
      ],
      "cta": {
        "type": "scheduleMeeting",
        "url": "https://cal.com/acme/intro",
        "ready": true,
        "issue": null
      },
      "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
      "lead_fields": {
        "required": [
          "linkedin_url"
        ],
        "optional": [
          "first_name",
          "last_name",
          "company",
          "email",
          "company_website",
          "external_ref"
        ]
      },
      "cost_per_asset": 3,
      "edit_url": "https://neuropage.io/home/acme/templates/founder-page"
    }
  ],
  "has_more": false
}
```

Errors: 401, 429, 500, 503.

### Create a template

`POST /templates`

Makes a template (the layout): which built-in sections a page has, in what order, and its call to action. Pass `brand_id` to link an existing brand as its look, or leave it out and pass `brand_id` on each job. A call to action with nowhere to go is refused with the reason, so a new template is always usable. Custom blocks, proof, pricing and the visual editor are in the app (`edit_url`). Free.

Request body:

```json
{
  "name": "Founder page",
  "sections": [
    "problem",
    "solution",
    "howItWorks",
    "faq"
  ],
  "cta": {
    "type": "scheduleMeeting",
    "url": "https://cal.com/acme/intro",
    "text": "Book a call"
  },
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d"
}
```

Response `201`:

```json
{
  "object": "template",
  "id": "tpl_568c6ef294b649bebed2353fffe98920",
  "name": "Founder page",
  "sections": [
    "hero",
    "problem",
    "solution",
    "howItWorks",
    "faq",
    "cta"
  ],
  "cta": {
    "type": "scheduleMeeting",
    "url": "https://cal.com/acme/intro",
    "ready": true,
    "issue": null
  },
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
  "lead_fields": {
    "required": [
      "linkedin_url"
    ],
    "optional": [
      "first_name",
      "last_name",
      "company",
      "email",
      "company_website",
      "external_ref"
    ]
  },
  "cost_per_asset": 3,
  "edit_url": "https://neuropage.io/home/acme/templates/founder-page"
}
```

Errors: 401, 403, 404, 409, 422, 429, 500, 503.

### Get a template

`GET /templates/{id}`

One template with its sections, call to action and own brand.

Response `200`:

```json
{
  "object": "template",
  "id": "tpl_568c6ef294b649bebed2353fffe98920",
  "name": "Founder page",
  "sections": [
    "hero",
    "problem",
    "solution",
    "howItWorks",
    "faq",
    "cta"
  ],
  "cta": {
    "type": "scheduleMeeting",
    "url": "https://cal.com/acme/intro",
    "ready": true,
    "issue": null
  },
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
  "lead_fields": {
    "required": [
      "linkedin_url"
    ],
    "optional": [
      "first_name",
      "last_name",
      "company",
      "email",
      "company_website",
      "external_ref"
    ]
  },
  "cost_per_asset": 3,
  "edit_url": "https://neuropage.io/home/acme/templates/founder-page"
}
```

Errors: 401, 404, 429, 500, 503.

## Jobs

Start work and follow it. Page jobs make one asset per lead; brand jobs read a website.

### Generate assets

`POST /jobs`

Make one personalized landing page per lead, from each lead's LinkedIn profile URL. 1 to 25 leads per job. The job is quoted first; with too few credits nothing starts (`402`). Invalid rows are rejected and the rest run. A lead that already has a page in the campaign is reused at no charge. Returns `202` with a running job; follow it with `GET /jobs/{id}?wait=50`. Never send the job again to check progress. Send `dry_run: true` to get the quote as a `200` JobQuote first: the credits it would cost, how many leads would get a new page or reuse one, and whether the balance covers it. Nothing is started.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | no | string | Any string up to 100 characters. The same key within 24 hours returns the first job (200) instead of starting another. |

Request body:

```json
{
  "type": "landing_page",
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
  "template_id": "tpl_568c6ef294b649bebed2353fffe98920",
  "leads": [
    {
      "linkedin_url": "https://www.linkedin.com/in/jane-doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "company": "Acme",
      "external_ref": "row-1"
    },
    {
      "linkedin_url": "https://www.linkedin.com/in/john-roe",
      "external_ref": "row-2"
    }
  ]
}
```

Response `202`:

```json
{
  "object": "job",
  "id": "job_5ce5d74e89b74e10a1dffaa9019b201a",
  "type": "assets",
  "asset_type": "landing_page",
  "status": "running",
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
  "template_id": "tpl_568c6ef294b649bebed2353fffe98920",
  "campaign_id": "cmp_5b5c31b9cf6447519e3a5eab4ad4797b",
  "counts": {
    "total": 4,
    "queued": 0,
    "processing": 3,
    "ready": 0,
    "failed": 0,
    "rejected": 1
  },
  "rejected": [
    {
      "position": 3,
      "external_ref": "row-4",
      "code": "invalid_linkedin_url",
      "message": "That is a company page. Paste the profile of a person at that company instead.",
      "credits_refunded": 0
    }
  ],
  "cost": {
    "quoted": 8,
    "charged": 8,
    "refunded": 0,
    "currency": "credits"
  },
  "refunded": false,
  "credits_refunded": 0,
  "refund_message": null,
  "credits_remaining": 4964,
  "eta": {
    "eta_at": "2026-10-27T13:40:52.238Z",
    "eta_seconds": 58
  },
  "poll_after_seconds": 15,
  "app_url": "https://neuropage.io/home/acme/campaigns/5b5c31b9-cf64-4751-9e3a-5eab4ad4797b",
  "created_at": "2026-10-27T13:39:51.035Z"
}
```

Errors: 400, 401, 402, 403, 404, 409, 422, 429, 500, 503.

### Get a job

`GET /jobs/{id}`

A job's status, counts, cost and ETA. With `wait`, the call returns as soon as anything changes. A page job is done when its status is `completed`, `completed_with_errors` or `failed`; then list its assets. There is no job-completion webhook: poll this, or send the job into a campaign that sends `lead.ready` to a webhook (see Webhooks).

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `wait` | query | no | integer | Hold the call up to this many seconds and return as soon as anything changes. |

Response `200`:

```json
{
  "object": "job",
  "id": "job_5ce5d74e89b74e10a1dffaa9019b201a",
  "type": "assets",
  "asset_type": "landing_page",
  "status": "running",
  "brand_id": "brd_c91200b9c0034964bad543c932f2853d",
  "template_id": "tpl_568c6ef294b649bebed2353fffe98920",
  "campaign_id": "cmp_5b5c31b9cf6447519e3a5eab4ad4797b",
  "counts": {
    "total": 4,
    "queued": 0,
    "processing": 3,
    "ready": 0,
    "failed": 0,
    "rejected": 1
  },
  "rejected": [
    {
      "position": 3,
      "external_ref": "row-4",
      "code": "invalid_linkedin_url",
      "message": "That is a company page. Paste the profile of a person at that company instead.",
      "credits_refunded": 0
    }
  ],
  "cost": {
    "quoted": 8,
    "charged": 8,
    "refunded": 0,
    "currency": "credits"
  },
  "refunded": false,
  "credits_refunded": 0,
  "refund_message": null,
  "credits_remaining": 4964,
  "eta": {
    "eta_at": "2026-10-27T13:40:52.238Z",
    "eta_seconds": 58
  },
  "poll_after_seconds": 15,
  "app_url": "https://neuropage.io/home/acme/campaigns/5b5c31b9-cf64-4751-9e3a-5eab4ad4797b",
  "created_at": "2026-10-27T13:39:51.035Z"
}
```

Errors: 401, 404, 422, 429, 500, 503.

## Assets

What a job made: one landing page per lead, with its URL and status.

### List assets

`GET /assets`

Every asset in a job (in the order you sent the leads) or in a campaign (newest first). Pass exactly one of `job_id` or `campaign_id`.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `job_id` | query | no | string | Assets of this job. |
| `campaign_id` | query | no | string | Assets of this campaign. |
| `type` | query | no | string: landing_page |  |
| `limit` | query | no | integer |  |
| `starting_after` | query | no | string | The last asset id of the previous page. |

Response `200`:

```json
{
  "object": "list",
  "data": [
    {
      "object": "asset",
      "id": "ast_30d2ee14acbd4c36883c45d580ff2b0c",
      "type": "landing_page",
      "status": "ready",
      "job_id": "job_5ce5d74e89b74e10a1dffaa9019b201a",
      "campaign_id": "cmp_5b5c31b9cf6447519e3a5eab4ad4797b",
      "external_ref": "row-1",
      "lead": {
        "linkedin_url": "https://www.linkedin.com/in/jane-doe",
        "name": "Jane Doe",
        "company": "Acme"
      },
      "url": "https://pages.neuropage.io/acme/jane-doe-acme-x7k2p",
      "edit_url": "https://neuropage.io/home/acme/leads/jane-doe-acme-x7k2p",
      "progress": {
        "stage": "ready",
        "percent": 100
      },
      "error": null,
      "reused": false,
      "ready_at": "2026-10-27T13:41:06.941Z"
    }
  ],
  "has_more": false
}
```

Errors: 400, 401, 404, 422, 429, 500, 503.

### Get an asset

`GET /assets/{id}`

One lead's page: its status, progress, and the URL once ready. The URL is permanent.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `wait` | query | no | integer | Hold the call up to this many seconds and return as soon as anything changes. |

Response `200`:

```json
{
  "object": "asset",
  "id": "ast_30d2ee14acbd4c36883c45d580ff2b0c",
  "type": "landing_page",
  "status": "ready",
  "job_id": "job_5ce5d74e89b74e10a1dffaa9019b201a",
  "campaign_id": "cmp_5b5c31b9cf6447519e3a5eab4ad4797b",
  "external_ref": "row-1",
  "lead": {
    "linkedin_url": "https://www.linkedin.com/in/jane-doe",
    "name": "Jane Doe",
    "company": "Acme"
  },
  "url": "https://pages.neuropage.io/acme/jane-doe-acme-x7k2p",
  "edit_url": "https://neuropage.io/home/acme/leads/jane-doe-acme-x7k2p",
  "progress": {
    "stage": "ready",
    "percent": 100
  },
  "error": null,
  "reused": false,
  "ready_at": "2026-10-27T13:41:06.941Z"
}
```

Errors: 401, 404, 422, 429, 500, 503.

## Stats

Who opened their page: visits, scroll depth, CTA clicks, forms, meetings.

### Get asset stats

`GET /stats`

Which leads viewed their page: visits, deepest scroll, CTA clicks, form fills and booked meetings per asset, hottest first, with totals. Pass one of `job_id`, `campaign_id` or `asset_ids`.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `job_id` | query | no | string |  |
| `campaign_id` | query | no | string |  |
| `asset_ids` | query | no | string | Comma-separated ast_ ids, at most 100. |
| `since` | query | no | string | Only activity from this moment on. |

Response `200`:

```json
{
  "object": "stats",
  "since": "2026-10-20T00:00:00.000Z",
  "totals": {
    "assets": 3,
    "viewed": 1,
    "visits": 2,
    "cta_clicks": 1,
    "forms": 0,
    "meetings": 1
  },
  "data": [
    {
      "asset_id": "ast_30d2ee14acbd4c36883c45d580ff2b0c",
      "lead": {
        "name": "Jane Doe",
        "company": "Acme",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe"
      },
      "url": "https://pages.neuropage.io/acme/jane-doe-acme-x7k2p",
      "visits": 2,
      "first_viewed_at": "2026-10-27T15:02:11.000Z",
      "last_viewed_at": "2026-10-28T09:14:40.000Z",
      "max_scroll": 100,
      "cta_clicks": 1,
      "forms": 0,
      "meetings": 1
    },
    {
      "asset_id": "ast_4f9bf7c114744d66a0d88bf250fff16e",
      "lead": {
        "name": "John Roe",
        "company": "Roe Logistics",
        "linkedin_url": "https://www.linkedin.com/in/john-roe"
      },
      "url": "https://pages.neuropage.io/acme/john-roe-roe-logistics-x7k2p",
      "visits": 0,
      "first_viewed_at": null,
      "last_viewed_at": null,
      "max_scroll": 0,
      "cta_clicks": 0,
      "forms": 0,
      "meetings": 0
    }
  ]
}
```

Errors: 401, 404, 422, 429, 500, 503.

## Webhook events

What NeuroPage POSTs to your URL when a lead is ready or acts on their page. Webhooks are added in the app under Integrations, Webhooks; there is no API endpoint or MCP tool to register one yet. API jobs reach a webhook through a campaign_id whose Send stage uses it.

### Lead ready (lead.ready)

`POST {your webhook URL}`

**Fires when:** A lead's page is ready and its campaign sends the lead to this webhook: the campaign's **Autopilot, Send** stage uses the tool **Webhook** with this webhook picked, and the stage is armed. NeuroPage first waits for everything the stage requires (the page, and email or LinkedIn messages when picked). A manual send from the campaign sends it too. Once per lead: a lead already sent is skipped unless you send it again from the campaign. A paused campaign sends nothing.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. A timeout, network error, 408, 429 or 5xx is retried a few times within minutes; see Webhooks in the guide.

Request body:

```json
{
  "event": "lead.ready",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "email_subject_step_1": "A page we made for Analytical Engines",
  "email_opening_step_1": "Ada, I put together a short page on how you could ...",
  "li_connection_note": "Hi Ada, made something for you ...",
  "li_message_1": "Here is the page I mentioned ...",
  "source_fields": {
    "row_id": "r_123"
  }
}
```

### Page ready (page.ready)

`POST {your webhook URL}`

**Fires when:** A lead's landing page is hosted and has a permanent URL. Every campaign in the workspace, including pages made through the API or MCP. No Send-stage setup is required. Sent once per lead; a later successful delivery is not repeated.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. A timeout, network error, 408, 429 or 5xx is tried twice more in the next few seconds. There is no durable retry queue for these events yet.

Request body:

```json
{
  "event": "page.ready",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "job_id": "job_01example",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "source_fields": {
    "row_id": "r_123"
  }
}
```

### Job failed (job.failed)

`POST {your webhook URL}`

**Fires when:** An API or MCP asset job ended with no ready pages (every accepted lead failed or was canceled). Not sent when the job is completed_with_errors. Sent once per job. The body is job-level: `job_id`, `error`, `failed_lead_ids`. Brand-from-website jobs are not included yet.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. A timeout, network error, 408, 429 or 5xx is tried twice more in the next few seconds. There is no durable retry queue for these events yet.

Request body:

```json
{
  "event": "job.failed",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "job_id": "job_01example",
  "job_type": "landing_page",
  "error": "The page could not be generated.",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "failed_lead_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
```

### Page viewed (page.viewed)

`POST {your webhook URL}`

**Fires when:** The lead starts a new visit to their page. Your own previews from the app do not count. Every campaign in the workspace, the API campaign included.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. Sent once, not retried.

Request body:

```json
{
  "event": "page.viewed",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "country": "NL",
  "source_fields": {
    "row_id": "r_123"
  }
}
```

### CTA clicked (cta.clicked)

`POST {your webhook URL}`

**Fires when:** The lead clicks the page's call to action. Every campaign in the workspace.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. Sent once, not retried.

Request body:

```json
{
  "event": "cta.clicked",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "country": "NL",
  "source_fields": {
    "row_id": "r_123"
  }
}
```

### Form submitted (form.submitted)

`POST {your webhook URL}`

**Fires when:** The lead submits the form on their page. Carries `visitor_name` and `visitor_email` when given. Every campaign in the workspace.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. Sent once, not retried.

Request body:

```json
{
  "event": "form.submitted",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "country": "NL",
  "visitor_name": "Ada Lovelace",
  "visitor_email": "ada@example.com",
  "source_fields": {
    "row_id": "r_123"
  }
}
```

### Meeting booked (meeting.booked)

`POST {your webhook URL}`

**Fires when:** The lead books a meeting through the Calendly or Cal.com embed on their page. Carries `provider` and `scheduled_at`. Every campaign in the workspace.

NeuroPage sends `POST` with `Content-Type: application/json`, `User-Agent: NeuroPage-Webhooks/1.0` and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends `X-NeuroPage-Signature: t=<unix>,v1=<hex>`, where v1 is hex HMAC-SHA256 of `${t}.${body}` with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed. Sent once, not retried.

Request body:

```json
{
  "event": "meeting.booked",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "lead_id": "00000000-0000-0000-0000-000000000000",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "Test campaign",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
  "company": "Analytical Engines",
  "job_title": "Head of Growth",
  "company_domain": "example.com",
  "page_url": "https://pages.neuropage.io/example/ada-lovelace",
  "country": "NL",
  "provider": "calendly",
  "scheduled_at": "2026-01-08T10:00:00.000Z",
  "source_fields": {
    "row_id": "r_123"
  }
}
```
