{"id":15768,"library":"posthog-openapi-client","title":"PostHog OpenAPI Client","description":"This package provides a TypeScript client for interacting with the PostHog API, automatically generated from the PostHog OpenAPI schema. It aims to offer a type-safe and convenient way to access PostHog's functionalities programmatically, including managing events, persons, and insights. Currently at version 0.0.12, it is in its early stages of development, meaning the API surface may evolve rapidly and breaking changes are likely before a stable 1.0 release. The package is primarily designed for TypeScript environments and relies on environment variables for API key and base URL configuration. Its key differentiator is providing a pre-generated, typed client, saving developers the effort of manual API request handling and type definition.","status":"active","version":"0.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/Drakkar-Software/posthog-openapi-client","tags":["javascript","openapi","client","typescript","posthog"],"install":[{"cmd":"npm install posthog-openapi-client","lang":"bash","label":"npm"},{"cmd":"yarn add posthog-openapi-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add posthog-openapi-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { PosthogAPIClient } = require('posthog-openapi-client');","symbol":"PosthogAPIClient","correct":"import { PosthogAPIClient } from 'posthog-openapi-client';"},{"note":"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.","symbol":"Configuration options","correct":"import { PosthogAPIClient } from 'posthog-openapi-client';\nconst client = new PosthogAPIClient({ BASE: '...', TOKEN: '...' });"},{"note":"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.","symbol":"API service modules (e.g., events)","correct":"const response = await client.events.list();"}],"quickstart":{"code":"import { PosthogAPIClient } from 'posthog-openapi-client';\n\n// Ensure environment variables are set:\n// export POSTHOG_PERSONAL_API_KEY=YOUR_POSTHOG_API_KEY\n// export POSTHOG_BASE_URL=\"https://eu.posthog.com\" or \"https://app.posthog.com\"\n\nconst baseUrl = process.env.POSTHOG_BASE_URL ?? 'https://app.posthog.com';\nconst apiKey = process.env.POSTHOG_PERSONAL_API_KEY ?? '';\n\nif (!apiKey) {\n  console.error('Error: POSTHOG_PERSONAL_API_KEY environment variable is not set.');\n  process.exit(1);\n}\n\n// Initialize the client with base URL and API key\nconst client = new PosthogAPIClient({\n  BASE: baseUrl,\n  TOKEN: apiKey\n});\n\nasync function fetchSomeData() {\n  try {\n    // Example: Fetch recent events\n    // The actual method names and parameters depend on the generated client's structure.\n    // Assuming 'events' is a service and 'list' is a method on it.\n    const events = await client.events.list({\n      limit: 5,\n      // You might need to specify a project ID or other filters depending on your PostHog setup\n      // project_id: 123,\n    });\n    console.log(`Successfully fetched ${events.results?.length ?? 0} events.`);\n    if (events.results && events.results.length > 0) {\n      console.log('First event:', events.results[0]);\n    }\n\n    // Example: Fetch a list of persons\n    const persons = await client.persons.list({ limit: 3 });\n    console.log(`Successfully fetched ${persons.results?.length ?? 0} persons.`);\n    if (persons.results && persons.results.length > 0) {\n      console.log('First person:', persons.results[0]);\n    }\n\n  } catch (error) {\n    console.error('Failed to interact with PostHog API:', error);\n    if (error instanceof Error) {\n      console.error('Error message:', error.message);\n    }\n  }\n}\n\nfetchSomeData();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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' }`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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', ... })`.","cause":"The `POSTHOG_PERSONAL_API_KEY` environment variable is missing or empty, which the client uses for authentication.","error":"Error: POSTHOG_PERSONAL_API_KEY environment variable is not set."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'list')"},{"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.","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.","error":"AxiosError: Network Error (or similar HTTP client error)"}],"ecosystem":"npm"}