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

# API reference

> Write OpenAPI specs, endpoint descriptions, parameters, and deprecation notices for the Mixpanel API reference

The Mixpanel API reference lives under `/reference`. This page covers how to write the content in it: the OpenAPI specs that generate most of the pages, and the authentication and deprecation details readers rely on.

For code samples, placeholders, and regional API hosts, see [Code and examples](https://docs.mixpanel.com/docs/code-examples.md).

## Edit the spec, not the page

Most reference pages are generated from the OpenAPI specs in the `openapi/` directory. A generated page has an `openapi:` field in its frontmatter that points to an operation in a spec:

```yaml theme={"system"}
---
openapi: "/openapi/annotations.openapi.yaml POST /projects/{projectId}/annotations"
title: Create Annotations
---
```

The docs site builds the page's description, parameters, responses, and code samples from the spec. To change any of them, edit the spec. Keep the page's `title` the same as the operation's `summary` in the spec.

Some other reference pages are generated by a separate process and start with a comment saying not to edit them. Don't edit those pages directly.

The rules on this page apply to new specs, endpoints, and parameters. You don't need to rewrite existing ones to match.

## Resources

In the specs, a resource is a tag that groups related endpoints, such as Events or User Profiles.

* **Name:** a short noun phrase in sentence case, such as "Group profiles" or "Lookup tables."
* **Description:** one sentence that says what the endpoints in the group do together. End it with a period. Don't list the individual endpoints.

| Do | Don't |
| - | - |
| Manage user profiles and their properties. | Set, unset, append, and delete profile properties |

## Endpoints

Each endpoint operation needs a summary and a description.

### Summary

The summary is the endpoint's title. Use sentence case, start with a verb, and don't end it with a period.

* For an endpoint that acts on one item, use a singular noun with an article: "Get an annotation," "Delete a pipeline."
* For an endpoint that acts on a collection, use a plural noun: "List annotations," "Get annotation tags."

Choose a verb that matches the HTTP method:

| Method | Verbs |
| - | - |
| `GET` | Get, List |
| `POST` | Create, or a specific action such as Archive or Merge |
| `PUT`, `PATCH` | Update |
| `DELETE` | Delete |

### Description

Start with a verb that says what the endpoint does, and end with a period. Then add what the reader needs to call it:

* **Permissions:** the minimum role the caller needs, such as "Requires a role of at least Analyst."
* **Plan availability:** if the endpoint is limited to some plans, name them: "Available on the Growth and Enterprise plans."
* **Regions:** if the endpoint isn't available in every Data Residency region, say which regions it supports.

| Do | Don't |
| - | - |
| Creates an annotation on a project's timeline. Requires a role of at least Analyst. | This endpoint can be used to create annotations. |
| Lists the experiments in a workspace. | Experiments list |

Don't repeat the HTTP method or path in the description. The reference page shows them automatically.

## Parameters

Each parameter needs a name, a data type, a required or optional status, and a description. The name, type, and status come from the spec's structure. Write the description:

* **Strings, numbers, objects, and arrays:** use a noun phrase that says what the value is. "The name of the cohort."
* **Booleans:** start with a verb that says what `true` does. "Includes deleted events in the results."
* **End every description with a period.**
* **Use the present tense.** "Mixpanel validates the batch," not "Mixpanel will validate the batch."

Put defaults, limits, and allowed values in the spec's own fields, such as `default`, `minimum`, `maximum`, and `enum`. The reference page displays them automatically, so don't repeat them in the description. Use the description for anything those fields can't express, such as units or how two parameters interact.

| Do | Don't |
| - | - |
| The maximum number of results to return. (The limit is set in the spec's `maximum` field.) | Max results. Must be under the limit. |
| Validates the batch and returns an error for each event that fails. | When set to true, Mixpanel will validate the batch. |

## Authentication

State which credential each endpoint requires, and show the same credential in its samples:

* **Most Ingestion API endpoints** take a project token. Show it as `YOUR_PROJECT_TOKEN`.
* **Most other APIs** use a service account with HTTP basic authentication. In cURL samples, show it as `--user "<serviceaccount_username>:<serviceaccount_secret>"`.

Link to [Authentication Methods](https://docs.mixpanel.com/reference/authentication) rather than explaining authentication on every page.

Always use `https://` in URLs. Mixpanel APIs reject requests over plain HTTP.

## Deprecated endpoints and parameters

When an endpoint or parameter is deprecated but still works:

1. Set `deprecated: true` on the operation or parameter in the spec.
2. Add a notice to the start of its description with:
   * The date it was deprecated
   * What to use instead, with a link, or why there's no replacement
   * The date it stops working, if one is set
3. Announce the deprecation in the changelog.

Write full dates, such as March 3, 2027. Don't use ordinal dates or relative timing, such as "next quarter" or "soon."

| Do | Don't |
| - | - |
| Deprecated on January 15, 2026. Use the Create an annotation endpoint instead. This endpoint stops working on January 15, 2027. | This endpoint will be retired soon. Please migrate when convenient. |