API

This section of our Docs explains how to pull or push data from/to our API. PostHog has an API available on all tiers of PostHog cloud pricing, including the free tier, and for every self-hosted version.

Please note that PostHog makes use of two different APIs, serving different purposes and using different mechanisms for authentication.

One API is used for pushing data into PostHog. This uses the 'Team API Key' that is included in the frontend snippet. This API Key is public, and is what we use in our frontend integration to push events into PostHog, as well as to check for feature flags, for instance.

The other API is more powerful and allows you to perform any action as if you were an authenticated user utilizing the PostHog UI. It is mostly used for getting data out of PostHog, as well as other private actions such as creating a feature flag. This uses a 'Personal API Key' which you need to create manually (instructions below). This API Key is private and you should not make it public nor share it with anyone. It gives you access to all the data held by your PostHog instance, which includes sensitive information.

These API Docs refer mostly to the private API, performing authentication as outlined below. The only exception is the POST-only public endpoints section. This section explicitly informs you on how to perform authentication. For endpoints in all other sections, authentication is done as described below.

Authentication

Personal API keys (Recommended)

Personal API keys allow full access to your account, just like e-mail address and password, but you can create any number of them and each one can invalidated individually at any moment. This makes for greater control for you and improved security of stored data.

How to obtain a personal API key

1. Click on your name/avatar on the top right.
2. Click the gear next to your name to access 'Account settings'.
3. Navigate to the 'Personal API Keys' section.
4. Click "+ Create a Personal API Key".
5. Give your new key a label – it's just for you, usually to describe the key's purpose.
6. Click 'Create Key'.
7. There you go! At the top of the list you should now be seeing your brand new key. Immediately copy its value, as you'll never see it again after refreshing the page. But don't worry if you forget to copy it – you can delete and create keys as much as you want.

How to use a personal API key

There are three options:

1. Use the Authorization header and Bearer authentication, like so:
   JavaScript

   const headers = {
       Authorization: `Bearer ${POSTHOG_PERSONAL_API_KEY}`
   }

2. Put the key in request body, like so:
   JavaScript

   const body = {
       personal_api_key: POSTHOG_PERSONAL_API_KEY
   }

3. Put the key in query string, like so:
   JavaScript

   const url = `https://posthog.example.com/api/event/?personal_api_key=${POSTHOG_PERSONAL_API_KEY}`

Any one of these methods works, but only the value encountered first (in the order above) will be used for authenticaition! showTitle: false showSidebar: false

For PostHog Cloud, use app.posthog.com as the host address.

Specifying a project when using the API

By default, if you're accessing the API, PostHog will return results from the last project you visited in the UI. To override this behavior, you can pass in your Project API Key (public token) as a query parameter in the request. This ensures you will get data from the project associated with that token.

Example

api/event/?token=my_project_api_key

cURL example for self-hosted PostHog

POSTHOG_PERSONAL_API_KEY=qTjsppKJqYLr2YskbsLXmu46eW1oH0r3jZkmKaERlf0
curl \
--header "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
https://posthog.example.com/api/person/

cURL example for PostHog Cloud

POSTHOG_PERSONAL_API_KEY=qTjsppKJqYLr2YskbsLXmu46eW1oH0r3jZkmKaERlf0
curl \
--header "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
https://app.posthog.com/api/person/

Tips

• The /users/@me/ endpoint gives you useful information about the current user.
• The /api/event_definition/ and /api/property_definition endpoints provide the possible event names and properties you can use throughout the rest of the API.
• The maximum size of a POST request body is governed by settings.DATA_UPLOAD_MAX_MEMORY_SIZE, and is 20MB by default.

Pagination

Sometimes requests are paginated. If that's the case, it'll be in the following format:

{
    "next": "https://posthog.example.com/api/person/?cursor=cD0yMjgxOTA2",
    "previous": null,
    "results": [
        ...
    ]
}

You can then just call the "next" URL to get the next set of results.

Contributing to API docs

API docs are generated using drf-spectacular. It looks at the Django models and djangorestframework serializers.

Note: We don't automatically add new API endpoints to the sidebar, so you'll need to add those to sidebar.json

You can add a help_text="Field that does x" attribute to any Model or Serializer field to help users understand what a specific field is used for:

class Insight(models.Model):
    last_refresh: models.DateTimeField = models.DateTimeField(blank=True, null=True, help_text="When the cache for the result of this insight was last refreshed.")

class InsightSerializer(TaggedItemSerializerMixin, InsightBasicSerializer):
    filters_hash = serializers.CharField(
        read_only=True,
        help_text="A hash of the filters that generate this insight.",
    )

To add a description to the top of a page, add a comment to the viewset class:

class InsightViewSet(TaggedItemViewSetMixin, StructuredViewSetMixin, viewsets.ModelViewSet):
    """
    Stores saved insights along with their entire configuration options. Saved insights can be stored as standalone
    reports or part of a dashboard.
    """

You can do the same thing for specific endpoints.

@action(methods=["GET", "POST"], detail=False)
def trend(self, request: request.Request, *args: Any, **kwargs: Any) -> Response:
    """
    Test comment, which [even supports markdown](https://example.com)
    """

To check what any changes will roughly look like locally, you can go to http://127.0.0.1:8000/api/schema/redoc/.

Insights serializer

The serializer for insight lives here. Each time an insight gets created we check it against these serializers, and we'll send an error to Sentry (but not the user) if it doesn't match, to ensure the API docs are up to date.

Documenting custom endpoints

If you have an @action endpoint or a custom endpoint (that doesn't use DRF) you can still document by providing a serializer for the request and response.

from drf_spectacular.utils import OpenApiResponse
from posthog.api.documentation import extend_schema
@extend_schema(
    request=FunnelSerializer,
    responses=OpenApiResponse(
        response=FunnelStepsResultsSerializer,
        description="Note, if funnel_viz_type is set the response will be different.",
     ),
    methods=["POST"],
    tags=["funnel"],
    operation_id="Funnels",
)
@action(methods=["GET", "POST"], detail=False)
def funnel(self, request: request.Request, *args: Any, **kwargs: Any) -> Response:

Testing API docs locally

To test or develop the API docs locally, you need to create a personal API key (see top of this page) and then export it before running gatsby, in the same terminal window:

export POSTHOG_PERSONAL_API_KEY=yourkey