# API overview

The HTTP interface to your Mimeo. This is how your application, your checkout, and your coding agent put data into Mimeo and read it back.

## Base URL

There is no shared Mimeo API host. Your Mimeo is the API — the base URL is your own domain:

```
https://your-mimeo.com/api/v1/…
```

Every path in these docs is relative to that. Single-tenant means your data never travels through anyone else's infrastructure to reach you.

## Authentication

Authenticated endpoints take a bearer token in the `Authorization` header:

```
Authorization: Bearer mm_your_token_here
```

Tokens start with the `mm_` prefix, which makes them easy to spot in logs and secret scanners.

### Creating a token

In the app, go to **Settings → Agents & API** and create one. You give it a name so you can tell your agent's token from your checkout's token later.

**The token is shown once.** Copy it when it's created — your Mimeo stores it hashed and cannot show it to you again. If you lose it, revoke it and make a new one.

Every token can be **revoked** at any time, and each one shows its **last used** time so you can spot tokens that are no longer needed or being used from somewhere you didn't expect.

### No scopes

Tokens have **full access**. There is no scoping or permissioning. Treat every token as equivalent to full control of your Mimeo: keep them in your secret manager, never in client-side code, and issue separate named tokens per integration so you can revoke one without breaking the rest.

## Requests and responses

Send JSON, get JSON. Include `Content-Type: application/json` on requests with a body.

### Errors

Errors come back in a consistent shape:

```
{ "error": "Invalid or missing API token" }
```

The HTTP status carries the category and the `error` string explains the specifics. Endpoints that process multiple items at once — notably [events](/content/docs/api/events.html) — additionally report per-item outcomes in the response body, so a batch can partially succeed.

## The public exception

The [subscription-management endpoints](/content/docs/api/subscriptions.html) are the one part of the API that does **not** use a bearer token. They're public, and authenticated by the signed token in the URL itself.

That's deliberate. Those endpoints exist so you can build your own unsubscribe page, and that page runs in your subscribers' browsers, where an API token could never safely go.

## The endpoints

| Endpoint | Purpose |
| --- | --- |
| `POST /api/v1/events` | [Everything that happens](/content/docs/api/events.html) — signups, opt-ins, purchases, payments, subscriptions |
| `GET /api/v1/events` | [The event feed](/content/docs/api/events.html#reading-events/index.html) — everything that happened, newest first, filterable by name, source, person and time window |
| `GET /api/v1/event_types` | [The event registry](/content/docs/api/events.html#event-types/index.html) — every name this instance has seen, with counts, payload shapes and what listens for each |
| `GET /api/v1/field_definitions` | [Discover this install's custom-field schema](/content/docs/api/events.html#field-definitions/index.html) |
| `GET /api/v1/people/:id_or_email` | [Read one person](/content/docs/api/events.html#read-a-person/index.html), including fields, tags, attribution, and lifetime spend |
| `POST /api/v1/imports` and friends | [CSV import](/content/docs/api/imports.html) — upload, map columns, preview, commit, and poll for the report; full parity with the UI wizard |
| `GET /api/v1/flows` and friends | [Build, validate, dry-run and activate flows](/content/docs/api/flows.html) — full parity with the UI |
| `GET /api/v1/segments` and friends | [Create, check, count and read segments](/content/docs/api/segments.html) by key — full parity with the UI |
| `GET /api/v1/emails` and friends | [The email library](/content/docs/api/emails.html) — CRUD, the shared-vs-copy contract, and `fork` |
| `GET /api/v1/media` and friends | [The media library](/content/docs/api/media.html) — multipart upload, alt text, and deletion |
| `GET /api/v1/templates` and friends | [Layouts and components](/content/docs/api/templates.html) — the HTML and CSS an email is dressed in, plus the default layout |
| `GET /api/v1/themes` and friends | [Themes](/content/docs/api/themes.html) — the colors, fonts and page shape a layout is built from |
| `GET /api/v1/sequences` and friends | [Sequences and their steps](/content/docs/api/sequences.html) — full parity with the UI |
| `GET /api/v1/broadcasts` and friends | [Broadcasts](/content/docs/api/broadcasts.html) — compose, schedule, send now, cancel |
| `GET /api/v1/guards` and friends | [Send-time guards](/content/docs/api/guards.html) — create, toggle, scope |
| `GET /api/v1/definitions`, `POST …/diff`, `POST …/apply` | [Everything you author, as files](/content/docs/api/definitions.html) — the three calls the CLI wraps |
| `GET /api/v1/settings` and `PATCH` | [The writable settings](/content/docs/api/settings.html) — tunables, send windows, brand |
| `GET /api/v1/reporting/…` | Read-only reporting for emails, sequences, flows and broadcasts — the same numbers as the UI pages |
| `GET /api/v1/tags`, `/products`, `/queue` | [Read-only lookups](/content/docs/api/flows.html#lookups/index.html) so a flow definition can reference real records |
| `POST /webhooks/email/:provider` | [Inbound provider webhooks](/content/docs/api/webhooks.html) — deliveries, bounces, complaints (verified per adapter) |
| `GET /api/v1/subscription/:token` | [Subscription status](/content/docs/api/subscriptions.html) (public) |
| `POST /api/v1/subscription/:token/unsubscribe` | [Unsubscribe](/content/docs/api/subscriptions.html) (public) |
| `POST /api/v1/subscription/:token/resubscribe` | [Resubscribe](/content/docs/api/subscriptions.html) (public) |
| `POST /u/:token` | [RFC 8058 one-click unsubscribe](/content/docs/api/subscriptions.html#one-click/index.html) (public, called by mail clients) |
| `GET /o/:token`, `GET /l/:token` | [Open pixel and link redirect](/content/docs/api/tracking.html) — Mimeo generates these; you never call them directly |

## Start here

If you're wiring up an integration or pointing an agent at your Mimeo, read [the event contract](/content/docs/api/events.html) first. Practically everything that gets data into Mimeo goes through that one endpoint.