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

# API Reference

> Create an API key, authenticate requests to the Popcorn API, and find the endpoints for sending templates and receiving delivery status.

The Popcorn API lets your own systems send approved WhatsApp template messages through your connected WhatsApp number and receive delivery status updates back. It is meant for developers integrating an order system, CRM, or automation tool with Popcorn. Everything else, from campaigns to inbox triage, is done in the dashboard or through [AI assistants](https://docs.trypopcorn.ai/ai-assistants/overview.md).

## What the API covers

| Endpoint | What it does |
| - | - |
| `POST /api/v2/template/send` | Send a template to one phone number, with tracking, async mode, and webhook callbacks. See [Send a template](https://docs.trypopcorn.ai/api-reference/templates/send.md). |
| `POST /template/send` | The standard send endpoint without tracking. See [Send a template](https://docs.trypopcorn.ai/api-reference/templates/send.md). |
| `GET /template` | List the templates in your workspace with their IDs, languages, and approval status. |
| `GET /api/v2/template/health` | Check that the API is up and your key is accepted. |
| Message Status Webhook | Popcorn calls your URL when a tracked message is sent, delivered, read, or fails. See [Message status webhooks](https://docs.trypopcorn.ai/api-reference/webhooks/message-status.md). |

Base URL: `https://api.trypopcorn.ai`

## Before you start

* A WhatsApp number connected under **Integrations** and at least one template approved by Meta. See [Connect a WhatsApp number](https://docs.trypopcorn.ai/channels/whatsapp.md) and [Templates](https://docs.trypopcorn.ai/campaigns/templates.md).
* A role that can manage API keys. By default the Owner and Admin roles can create and revoke keys; the Manager role can only view the list. See [Team and roles](https://docs.trypopcorn.ai/settings/team-and-roles.md).

## Create an API key

**1. Open the developer settings**

Go to **Settings → API keys and webhooks** (in the **Developer** group). The **API keys** panel reads "Use a key when your own server calls Popcorn AI."

**2. Create the key**

Click **Create API key** (with no keys yet the page reads **No API keys yet**, with the same button), enter a **Name (optional)** such as `Production`, and click **Create key**. You see **API key created**. A key with no name is called **Default**.

**3. Copy it now**

**Copy your API key** shows the full key once: "You won't see this key again. Store it somewhere safe." Click **Copy**, then **Done**. The dialog closes only with **Done**. After that the list shows only a masked form, such as `sk-...abcd`.

Keys start with `sk-`. The table shows each key's **Name**, **Created** date, **Last used** date (or **Never used**), and **Status** (**Active** or **Revoked**). To remove a key, click **Revoke**, then **Revoke key** on "Revoke *name*?" ("Apps using this key lose access right away. This can't be undone."). You see **API key revoked**; the key cannot be restored, and revoked keys stay in the list.

> [!NOTE]
>
> Keep API keys for backend integrations, where your own server calls Popcorn. To let ChatGPT, Claude, or Codex work in your workspace, use [AI assistants](https://docs.trypopcorn.ai/ai-assistants/overview.md) instead; that connection needs no API key.

## Authenticate requests

Send the key in the `POPCORN-API-KEY` header on every request:

```bash theme={null}
curl https://api.trypopcorn.ai/api/v2/template/health \
  -H "POPCORN-API-KEY: sk-your_popcorn_api_key"
```

```json theme={null}
{
  "status": "ok",
  "service": "template-v2-api",
  "version": "2.0",
  "timestamp": "2026-09-01T10:30:00.000Z"
}
```

The `/api/v2` endpoints also accept `Authorization: Bearer sk-your_popcorn_api_key`. The `/template` endpoints accept only `POPCORN-API-KEY`.

Each key belongs to one workspace, the one you were in when you created it. Requests act on that workspace's templates, WhatsApp numbers, and Inbox; you cannot address another workspace with a key.

## Authentication errors

| HTTP status | Response | Cause |
| - | - | - |
| `401` | `{"error": "API Key not included in headers."}` | No `POPCORN-API-KEY` header on a `/template` endpoint. |
| `401` | `{"success": false, "error": {"code": "UNAUTHORIZED", "message": "API Key or Authorization header required"}}` | No key on an `/api/v2` endpoint. |
| `401` | `{"error": "Unauthorized", "message": "invalid api key"}` | The key does not exist or has been revoked. |
| `401` | `{"error": "Unauthorized", "message": "api key must start with sk-"}` | The header value is not a Popcorn key. |
| `401` | `{"error": "Unauthorized", "message": "organization suspended"}` | The workspace is suspended, for example after a lapsed subscription. See [Top-ups and renewal](https://docs.trypopcorn.ai/billing/top-ups-and-renewal.md). |
| `403` | `{"error": "Unauthorized", "message": "The specified phone number does not belong to this organization"}` | A `POPCORN-PHONE-NUMBER` header names a number that is not connected to your workspace. |

## Choosing between the API and AI assistants

| Use the API when | Use AI assistants when |
| - | - |
| Another system needs to send a template automatically, for example an order confirmation from your ERP. | A person wants to run the workspace in natural language from ChatGPT, Claude, or Codex. |
| You need delivery status pushed to your server. | You need campaigns, inbox triage, customers, products, orders, agents, or knowledge, none of which the API exposes. |
| You are building a backend integration with a long-lived key. | You want access tied to a user, their role, and an approval screen instead of a key. |

## Related

> [card] [Send a template](https://docs.trypopcorn.ai/api-reference/templates/send.md)
>
> Request and response formats for both send endpoints, and how to list templates.

> [card] [Message status webhooks](https://docs.trypopcorn.ai/api-reference/webhooks/message-status.md)
>
> Configure the webhook URL, token, and events, and read the payload.

> [card] [Templates](https://docs.trypopcorn.ai/campaigns/templates.md)
>
> Create templates and get them approved by Meta before sending.

> [card] [AI assistants](https://docs.trypopcorn.ai/ai-assistants/overview.md)
>
> Run your workspace from ChatGPT, Claude, or Codex without an API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.