Skip to main content
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.

​
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:
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.

​
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:

​
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.
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.

​
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 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.”