> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer API

> REST API with Personal Access Token authentication. Manage contacts, campaigns, brand settings, and AI drafts programmatically.

## Overview

The Nudgen Developer API gives scripts, internal tools, and AI agents a predictable REST interface for working with your Nudgen workspace.

<CardGroup cols={3}>
  <Card title="PAT auth" icon="shield-check">
    Authenticate REST requests with a Personal Access Token.
  </Card>

  <Card title="Campaign operations" icon="send">
    Create campaigns, schedule launches, and read delivery stats.
  </Card>

  <Card title="Agent-ready" icon="bot">
    Give Codex, Claude Code, Cursor, and custom agents structured access.
  </Card>
</CardGroup>

## Why this matters

A PAT lets you automate real marketing workflows without sharing your dashboard session. You can create contacts, draft campaign copy, create campaigns, and schedule sends from trusted developer tools while keeping token access revocable.

## Authentication

Create a Personal Access Token from **Settings -> API Keys** in the Nudgen dashboard. Store it securely and pass it with every request:

```bash theme={null}
Authorization: Bearer <your-pat>
```

Example:

```bash theme={null}
curl https://nudgen.net/api/v1/user/me \
  -H "Authorization: Bearer <your-pat>"
```

<Warning>
  PATs are shown only once. Revoke old or exposed tokens from **Settings -> API Keys**.
</Warning>

## Base URL

```text theme={null}
https://nudgen.net
```

## Interactive API playground

Use the **API Playground** tab next to **Guides** for a Swagger-style playground. Each endpoint is generated from `openapi.json`, includes request and response schemas, and can prefill examples for cURL, JavaScript, and Python.

Paste your PAT into the playground's bearer token field before sending requests. Playground calls hit the live Nudgen API, so use test contacts and drafts unless you intend to create or launch real campaigns.

## REST endpoints

### Identity and workspace

| Method | Endpoint          | Description                                   |
| ------ | ----------------- | --------------------------------------------- |
| `GET`  | `/api/v1/user/me` | Get the authenticated user.                   |
| `GET`  | `/api/v1/teams`   | List workspaces available to the token owner. |

### Contacts

| Method   | Endpoint               | Description                                                                 |
| -------- | ---------------------- | --------------------------------------------------------------------------- |
| `GET`    | `/api/v1/contacts`     | List contacts with `page`, `limit`, `search`, `tags`, and `status` filters. |
| `POST`   | `/api/v1/contacts/add` | Create a contact.                                                           |
| `GET`    | `/api/v1/contacts/:id` | Get a contact.                                                              |
| `PATCH`  | `/api/v1/contacts/:id` | Update a contact.                                                           |
| `DELETE` | `/api/v1/contacts/:id` | Delete a contact.                                                           |

Create a contact:

```bash theme={null}
curl -X POST https://nudgen.net/api/v1/contacts/add \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nathan@example.com",
    "name": "Nathan Nguyen",
    "tags": ["api-test"]
  }'
```

### Campaigns

| Method | Endpoint                           | Description                                              |
| ------ | ---------------------------------- | -------------------------------------------------------- |
| `GET`  | `/api/v1/campaigns`                | List campaigns in the active workspace.                  |
| `POST` | `/api/v1/campaigns`                | Create a campaign draft or scheduled campaign.           |
| `GET`  | `/api/v1/campaigns/:id`            | Get campaign details.                                    |
| `PUT`  | `/api/v1/campaigns/:id`            | Update an existing campaign.                             |
| `POST` | `/api/v1/campaigns/:id/launch`     | Launch now or schedule a campaign.                       |
| `GET`  | `/api/v1/campaigns/:id/stats`      | Get delivery, open, click, bounce, and complaint stats.  |
| `GET`  | `/api/v1/campaigns/:id/progress`   | Get campaign sending progress.                           |
| `GET`  | `/api/v1/campaigns/:id/recipients` | List campaign recipients.                                |
| `POST` | `/api/v1/campaigns/test-send`      | Send a test email without creating dashboard send stats. |

Create a draft campaign:

```bash theme={null}
curl -X POST https://nudgen.net/api/v1/campaigns \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API launch test",
    "goal": "Invite contacts to try Nudgen.",
    "subject": "Try Nudgen",
    "html": "<p>Ready to launch smarter email?</p>",
    "link": "https://nudgen.net",
    "audienceType": "manual",
    "audienceContactIds": ["contact_id"]
  }'
```

Schedule an existing campaign:

```bash theme={null}
curl -X POST https://nudgen.net/api/v1/campaigns/campaign_id/launch \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "sendNow": false,
    "scheduledAt": "2026-05-21T06:46:52.128Z"
  }'
```

Send immediately by setting `sendNow` to `true`, or by creating a campaign with `sendNow: true`.

<Warning>
  Launching a campaign schedules real email. Use `/api/v1/campaigns/test-send` for inbox previews that should not appear as launched campaigns in dashboard stats.
</Warning>

### Brand settings

| Method  | Endpoint                 | Description                                                        |
| ------- | ------------------------ | ------------------------------------------------------------------ |
| `GET`   | `/api/v1/settings/brand` | Read brand name, website, sender email, logo, and design settings. |
| `PATCH` | `/api/v1/settings/brand` | Update brand settings.                                             |

### AI draft generation

| Method | Endpoint              | Description                                                     |
| ------ | --------------------- | --------------------------------------------------------------- |
| `POST` | `/api/v1/ai/generate` | Generate an email subject and HTML draft from campaign context. |

```bash theme={null}
curl -X POST https://nudgen.net/api/v1/ai/generate \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignGoal": "Write a short retention email inviting users to try Nudgen.",
    "link": "https://nudgen.net",
    "personalizationMode": "off"
  }'
```

## MCP server

Use [Nudgen MCP](/en/agents/mcp) when your agent supports Model Context Protocol tools. MCP uses the same Personal Access Token as the REST API, but exposes Nudgen as agent-callable tools instead of conventional HTTP endpoints.

<Card title="MCP server setup" icon="bot" href="/en/agents/mcp">
  Install Nudgen MCP in Claude Code, Cursor, Windsurf, Codex CLI, or a generic MCP client.
</Card>

## Responses and errors

Successful responses return JSON. Validation errors return `400`, expired or missing tokens return `401`, insufficient plan access returns `403`, missing resources return `404`, and rate limits return `429`.

All data is scoped to the token owner's active workspace.