PostHog OpenAPI Client

Common errors

• Error: POSTHOG_PERSONAL_API_KEY environment variable is not set.

  cause The `POSTHOG_PERSONAL_API_KEY` environment variable is missing or empty, which the client uses for authentication.
  fix Set the `POSTHOG_PERSONAL_API_KEY` environment variable in your shell (e.g., `export POSTHOG_PERSONAL_API_KEY=YOUR_KEY`) or pass it directly to the client constructor: `new PosthogAPIClient({ TOKEN: 'YOUR_KEY', ... })`.

• TypeError: Cannot read properties of undefined (reading 'list')

  cause An API service module (e.g., `client.events`) or method (e.g., `client.events.list`) does not exist on the client instance, likely due to an outdated client or a typo.
  fix Verify the exact structure and method names by inspecting the generated client code or the PostHog API documentation. Ensure your `posthog-openapi-client` package is up-to-date with the latest PostHog API schema.

• AxiosError: Network Error (or similar HTTP client error)

  cause The client failed to connect to the PostHog API, often due to an incorrect `POSTHOG_BASE_URL`, network issues, or CORS restrictions in browser environments.
  fix Check that `POSTHOG_BASE_URL` is correctly set (e.g., `https://app.posthog.com` or `https://eu.posthog.com`). Verify your network connection and ensure no firewall or proxy is blocking access. For browser usage, check for CORS policies.

Warnings

• breaking As a pre-1.0.0 package (version 0.0.12), the API surface is unstable. Expect frequent breaking changes to method names, parameter types, and response structures in minor and patch releases.
  Fix: Regularly consult the package's changelog or regenerate your client from the latest PostHog schema if you are maintaining a fork. Pin exact versions (`"posthog-openapi-client": "0.0.12"`) to prevent unexpected breaks.
• gotcha The client relies on `POSTHOG_PERSONAL_API_KEY` and `POSTHOG_BASE_URL` environment variables by default. Forgetting to set these will lead to authentication or connection errors at runtime.
  Fix: Ensure these environment variables are correctly set in your execution environment. For programmatic configuration, pass the base URL and API key directly to the `PosthogAPIClient` constructor as `{ BASE: 'your_url', TOKEN: 'your_key' }`.
• gotcha The client is generated from PostHog's OpenAPI schema. If PostHog updates its API and a new version of this package isn't released, your client might become out-of-date, potentially leading to incorrect types or missing API endpoints.
  Fix: Monitor the `posthog-openapi-client` npm page for updates. If you require the absolute latest schema and no package update is available, you may need to regenerate the client locally using `openapi-typescript-codegen` as described in the package's README.

Install

• npm install posthog-openapi-client npm
• yarn add posthog-openapi-client yarn
• pnpm add posthog-openapi-client pnpm

Imports

• PosthogAPIClient
  wrong:

  const { PosthogAPIClient } = require('posthog-openapi-client');

  correct:

  import { PosthogAPIClient } from 'posthog-openapi-client';

  The client is designed for modern JavaScript/TypeScript environments and is best used with ES Module imports. CommonJS `require` syntax is generally not recommended and may not work as expected for this generated client.
• Configuration options

  import { PosthogAPIClient } from 'posthog-openapi-client';
  const client = new PosthogAPIClient({ BASE: '...', TOKEN: '...' });

  While environment variables are suggested in the README, the client constructor often accepts a configuration object with `BASE` for the API URL and `TOKEN` for the personal API key, allowing for programmatic setup.
• API service modules (e.g., events)

  const response = await client.events.list();

  Specific API functionalities (like `events`, `persons`, `actions`) are exposed as properties on the `PosthogAPIClient` instance, following common OpenAPI client generation patterns. These are accessed directly via the client object, not imported individually.

Quickstart

This quickstart demonstrates how to initialize the `PosthogAPIClient` using environment variables and then make authenticated API calls to fetch events and persons from your PostHog instance.

import { PosthogAPIClient } from 'posthog-openapi-client';

// Ensure environment variables are set:
// export POSTHOG_PERSONAL_API_KEY=YOUR_POSTHOG_API_KEY
// export POSTHOG_BASE_URL="https://eu.posthog.com" or "https://app.posthog.com"

const baseUrl = process.env.POSTHOG_BASE_URL ?? 'https://app.posthog.com';
const apiKey = process.env.POSTHOG_PERSONAL_API_KEY ?? '';

if (!apiKey) {
  console.error('Error: POSTHOG_PERSONAL_API_KEY environment variable is not set.');
  process.exit(1);
}

// Initialize the client with base URL and API key
const client = new PosthogAPIClient({
  BASE: baseUrl,
  TOKEN: apiKey
});

async function fetchSomeData() {
  try {
    // Example: Fetch recent events
    // The actual method names and parameters depend on the generated client's structure.
    // Assuming 'events' is a service and 'list' is a method on it.
    const events = await client.events.list({
      limit: 5,
      // You might need to specify a project ID or other filters depending on your PostHog setup
      // project_id: 123,
    });
    console.log(`Successfully fetched ${events.results?.length ?? 0} events.`);
    if (events.results && events.results.length > 0) {
      console.log('First event:', events.results[0]);
    }

    // Example: Fetch a list of persons
    const persons = await client.persons.list({ limit: 3 });
    console.log(`Successfully fetched ${persons.results?.length ?? 0} persons.`);
    if (persons.results && persons.results.length > 0) {
      console.log('First person:', persons.results[0]);
    }

  } catch (error) {
    console.error('Failed to interact with PostHog API:', error);
    if (error instanceof Error) {
      console.error('Error message:', error.message);
    }
  }
}

fetchSomeData();