> For the complete documentation index, see [llms.txt](https://documentation.alpaco.email/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alpaco.email/account-settings/rest-api.md).

# REST API

### Base Configuration & Auth

All API requests must be made over HTTPS and authenticated using your organization-level JSON Web Token (JWT). Each user can generate a JWT token on their profile page<br>

<figure><img src="/files/VqoVCuKZo8zb4rwG0Ftu" alt=""><figcaption></figcaption></figure>

**Base URL:** <mark style="color:$warning;">`https://platform.alpaco.email/api/mcp/v1/`</mark>

**Authentication Header:** <mark style="color:$warning;">`Bearer <your_organization_jwt>`</mark>

```http
Authorization: Bearer YOUR_ORGANIZATION_JWT
Content-Type: application/json
Accept: application/json
```

### Endpoint Lifecycle Matrix

<table><thead><tr><th width="249">Description</th><th>Endpoint</th><th>Method</th></tr></thead><tbody><tr><td>Retrieves active workspace brand identities, target audiences, and copywriting rules.</td><td><code>/brand/guidelines</code></td><td><strong>GET</strong></td></tr><tr><td>Lists all active templates <em>with</em> their block keys and allowed inputs.</td><td><code>/templates</code></td><td><strong>GET</strong></td></tr><tr><td>Searches for existing approved graphics, logos, and banners in your media library.</td><td><code>/assets?search={keyword}</code></td><td><strong>GET</strong></td></tr><tr><td>Compiles a brand-new design layout into a fresh HTML draft asset and returns a unique <code>id</code>.</td><td><code>/assemble</code></td><td><strong>POST</strong></td></tr><tr><td>Fetches the current raw JSON configuration tree state of a saved email layout draft.</td><td><code>/assemble/{email_id}</code></td><td><strong>GET</strong></td></tr><tr><td>Updates and re-compiles an existing email draft asset for seamless content iterations.</td><td><code>/assemble/{email_id}</code></td><td><strong>POST</strong></td></tr><tr><td>Retrieves active third-party ESP/CRM integration connection IDs (HubSpot, Braze, etc.).</td><td><code>/connections</code></td><td><strong>GET</strong></td></tr><tr><td>Pushes a finalized, compiled email design straight into your external marketing platform.</td><td><code>/export</code></td><td><strong>POST</strong></td></tr></tbody></table>

### Getting Started

Unlike traditional, rigid APIs that force you to memorize hundreds of syntax rules, the Alpaco API is discovery-driven and self-correcting.

You do not need a static instruction guide for every email layout in your workspace. Instead, you dynamically query our engine to find your template constraints, construct your payload, and rely on our real-time validation engine to guide you through any structural mistakes.:

#### Phase 1: Inspect

Before your code can assemble an email, it needs to know what layouts are valid in your specific workspace. You do this by calling the templates directory.

* The Endpoint: <mark style="color:$warning;">`GET /templates`</mark>
* The Goal: Capture your target <mark style="color:$warning;">`template_id`</mark> and read the <mark style="color:$warning;">`available_blocks`</mark> array.

{% hint style="info" %}
Look closely at the response. The API will explicitly tell you what block components are allowed (e.g., `article`, `products`) and the exact array keys (`header_text`, `body_text`) those blocks require. Your application holds these keys in memory to map your raw data correctly.
{% endhint %}

#### Phase 2: Listen

Once your application maps out the text, images, and layout choices, you shoot your composition payload to the compilation track.

* The Endpoint: <mark style="color:$warning;">`POST /assemble`</mark>
* The Goal: Render your raw JSON into bulletproof HTML markup.

If your code passes a typo (like writing `bodycopy` instead of `body_text`), or forgets a global parameter like the marketing `subjectline`, the Alpaco compiler will instantly stop and hand you a `422 Unprocessable Entity` response containing a highly explicit error path.

**Example of error response**

```json
{
  "success": false,
  "errors": {
    "design.blocks.0.values": "Invalid keys: [bodycopy]. Allowed keys for block 'article': [header_text, body_text]"
  }
}
```

{% hint style="info" %}
You don't need a manual to troubleshoot your formatting. Simply read the `errors` object. It acts as a real-time code reviewer, telling you exactly which array index failed and providing a list of allowed alternative keys to fix your script instantly.
{% endhint %}

#### Phase 3: Scale

When your payload clears the validator, the engine returns a successful response alongside a unique, tracked asset number.

* The Output: A unique, persistent database integer identifier (e.g., `"id": 771024`).

**Chaining your next actions:**

Once you have this tracking ID, you can interact with the layout indefinitely using simple lifecycle combinations:

1. Content Iterations (`GET /assemble/{id}`) and (`POST /assemble/{id}`): If an automated process or reviewer needs to adjust a headline later, you don't generate a new orphan draft. You run an update request against that exact asset ID, passing the entire content back with adjustments.
2. Platform Syncing (`POST /export`): When the campaign is perfect, pass the email `id` alongside your `esp_connection_id` to cleanly push the final layout directly into your email sending account, connected to your organization in Alpaco.