PostHog API Client

A type-safe, isomorphic API client for the PostHog v2 REST API.

Overview

This package provides a lightweight, fully-typed client for interacting with the PostHog API. It's generated from the official PostHog OpenAPI specification and built on top of openapi-typescript and openapi-fetch, offering significantly smaller bundle sizes compared to traditional code generators like openapi-generator.

Features

• Type Safety: Full TypeScript support with generated types from the official OpenAPI spec
• Automatic Rate Limiting: Built-in rate limiting that respects PostHog's Retry-After headers
• Isomorphic: Works in both server-side (Node.js, Deno) and browser environments
• Lightweight: Minimal bundle size using modern fetch-based architecture
• Queue Management: Intelligent request queuing to handle rate limits gracefully
• Configurable: Customizable options for different use cases

Installation

pnpm add posthog-api
# or
yarn add posthog-api
# or
npm install posthog-api

Quick Start

import { createPostHogClient } from "posthog-api";

// Create a client with your PostHog Personal API key
const client = createPostHogClient("your-personal-api-key-here");

// Example: List all experiments
// (Note all API endpoint strings are type-safe and discoverable via IntelliSense!)
const { data, error } = await client[
  "api/projects/:project_id/experiments/"
].GET({
  params: {
    // Request path, query, and body are type checked
    path: {
      project_id: "222222",
    },
  },
});

// Response data is typed as well
if (error) {
  console.error(`Error of type ${error.type}:`, error.message);
} else {
  console.log("Experiments data:", data);
}

API Reference

createPostHogClient(accessToken, options?)

Creates a new PostHog API client instance.

Parameters:

• accessToken (string, required): Your PostHog API key
• options (object, optional): Configuration options

Options:

• baseUrl (string, default: "https://us.posthog.com"): API base URL (e.g. "https://eu.posthog.com")
• All other options from openapi-fetch are supported

Returns: A configured API client

Examples

• Get a person (docs)

import { createPostHogClient } from "posthog-api";

const client = createPostHogClient(process.env.POSTHOG_PERSONAL_API_KEY!);

const { data, error } = await client[
  "/api/environments/{project_id}/persons/"
].GET({
  params: {
    path: {
      project_id: "222222",
    },
    query: {
      email: "[email protected]",
    },
  },
});

if (error) throw error;
console.log("Person:", data.results?.[0]);

• Delete a person (docs)

import { createPostHogClient } from "posthog-api";

const client = createPostHogClient(process.env.POSTHOG_PERSONAL_API_KEY!);

const { error } = await client[
  "/api/environments/{project_id}/persons/{id}/"
].DELETE({
  params: {
    path: {
      project_id: "222222",
      id: 1234, // person-id
    },
    query: { delete_events: false },
  },
});

if (error) throw error;
console.log("Person deleted");

Development

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm

Setup

1. Clone the repository
2. Install dependencies: pnpm install
3. Generate types: pnpm generate:openapi
4. Run tests: pnpm test

Scripts

• pnpm generate:openapi - Generate TypeScript types and client from OpenAPI spec
• pnpm update:openapi - Redownload the latest PostHog OpenAPI spec and then regenerate the client
• pnpm test - Run test suite
• pnpm test:watch - Run tests in watch mode
• pnpm lint - Run ESLint
• pnpm types:check - Check TypeScript types

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.