consuming-endpoints-from-client-code — Claude Code skill: setup & use
consuming-endpoints-from-client-code guides integrating PostHog endpoints into apps and services. Covers OpenAPI generation, variable formatting, and request handling.
MIT 322 installs ★ 80 updated 2026-10-24
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a claude-codeWhat consuming-endpoints-from-client-code does
This skill guides the caller-side integration of existing PostHog endpoints into client applications or backend services without modifying PostHog codebase. It inspects endpoint definitions using endpoint-get, exports OpenAPI 3.0 specs with endpoint-openapi-spec, and executes test calls via endpoint-run.
Requests target /api/projects/{team_id}/endpoints/{name}/run via POST. Authentication requires a personal API key with the endpoint:read scope passed as a Bearer token. Personal API keys must never be bundled into client-side web or mobile code, so requests must route through an intermediate server backend.
When an endpoint has materialisation enabled, omitting any declared variable triggers a 400 error. For generating clients, the skill guides feeding the exported spec into tools like @hey-api/openapi-ts, openapi-generator-cli, or oapi-codegen to build typed interfaces.
What it helps with
- generate typed client SDKs from PostHog OpenAPI specs
- structure request bodies with HogQL variables
- configure Bearer auth headers with endpoint:read scope
- resolve 400 errors caused by missing materialised variables
Example prompts for the agent
- Generate a TypeScript client for the user-retention endpoint using openapi-generator-cli
- What variables do I need to pass in the request body for this PostHog endpoint?
- Test this endpoint payload with endpoint-run before adding it to my backend
How to install consuming-endpoints-from-client-code
1Skills CLI (Vercel)
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a claude-code2Manually: put the files in place
~/.claude/skills/consuming-endpoints-from-client-code/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/consuming-endpoints-from-client-code/
1Skills CLI (Vercel)
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a codex2Manually: put the files in place
.agents/skills/consuming-endpoints-from-client-code/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a cursor2Manually: put the files in place
.cursor/skills/consuming-endpoints-from-client-code/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install PostHog/skills skills/omnibus/consuming-endpoints-from-client-code2Manually: put the files in place
.github/skills/consuming-endpoints-from-client-code/SKILL.md1Skills CLI (Vercel)
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a gemini-cli2Platform CLI
gemini skills install https://github.com/PostHog/skills --path skills/omnibus/consuming-endpoints-from-client-codeManually: put the files in place
.devin/skills/consuming-endpoints-from-client-code/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about consuming-endpoints-from-client-code
How to install consuming-endpoints-from-client-code in Claude Code?
Run npx skills add PostHog/skills --skill consuming-endpoints-from-client-code -a claude-code. The file will be placed in ~/.claude/skills/consuming-endpoints-from-client-code/SKILL.md.
What does consuming-endpoints-from-client-code do?
It guides AI agents on querying PostHog endpoints, generating typed API SDKs from OpenAPI specs, and handling request parameters.
Why does a materialised endpoint return a 400 error?
Materialised endpoints require every declared variable on each request as a safeguard against retrieving the full pre-aggregated dataset.
Source text
SKILL.md · MIT
---
name: consuming-endpoints-from-client-code
description: >
Wire a PostHog endpoint into a client app or SDK. Covers fetching the OpenAPI spec, generating a
typed client with openapi-generator or @hey-api/openapi-ts, sending the right auth header,
shaping the variables payload (HogQL code_name vs insight breakdown property), handling
rate-limit and materialised-endpoint error responses. Use when the user says "how do I call my
endpoint", "generate a client for this", or "what auth header do I use".
---
# Consuming endpoints from client code
This skill is the **caller-side** counterpart to `creating-an-endpoint`. It helps integrate an
existing endpoint into a separate codebase — a mobile app, server backend, customer dashboard,
or downstream pipeline. No PostHog code is modified here.
## When to use this skill
- "How do I call my endpoint?" / "What does a request look like?"
- "Generate a typed TypeScript / Python / Go client for this endpoint"
- "I'm getting a 401 calling the endpoint" / auth questions
- "The endpoint rejects my call when I omit `user_id`" → materialised-endpoint variable
questions
- "How do I handle rate limits?"
If the user is **creating** the endpoint, use `creating-an-endpoint` first.
## Available tools
| Tool | Purpose |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| `endpoint-get` | Full config for a named endpoint, including the query shape and required variables |
| `endpoint-openapi-spec` | OpenAPI 3.0 spec for one endpoint, ready to feed to a code generator |
| `endpoint-run` | A live call against the endpoint — useful to confirm a payload works before sharing it with the user's app |
## The endpoint URL
```text
/api/projects/{team_id}/endpoints/{name}/run
```
- `team_id` is the project ID (numeric). Available in PostHog under project settings, or via
`projects-get` if the user doesn't know it.
- `name` is the endpoint name — see `endpoints-get-all` if the user isn't sure.
- The trailing `/run` is required.
`POST` is the canonical method. `GET` also works for simple cases without a request body but
POST is preferred — variables go in the body.
## Auth
Endpoints are authenticated with a **personal API key**. The header is:
```http
Authorization: Bearer <key>
```
Keys are scoped — for endpoints, the key needs at least `endpoint:read`. If the user gets a 403,
they're usually missing the scope; if they get a 401, the key is missing or malformed.
Never put a personal API key in client-side code that's shipped to end users (mobile apps,
browser JS). Personal API keys grant scoped account access. For customer-facing apps, route
through the user's own backend, which holds the key.
## The request payload
```json
{
"variables": { "code_name_1": value, "code_name_2": value },
"limit": 100,
"offset": 0,
"refresh": "cache"
}
```
| Field | Notes |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variables` | Keyed by `code_name` for HogQL endpoints; for insight endpoints with breakdowns, key is the **breakdown property name** |
| `limit` | Max rows returned. |
| `offset` | Skip rows. Only HogQL endpoints |
| `refresh` | `"cache"` (return cached results if fresh enough), `"force"` (always recalculate), `"direct"` (bypass materialisation, materialised endpoints only). Default is `"cache"` |
Call `endpoint-get` to see the exact variable shape. The response includes the query definition
with declared variables — each variable's `code_name` is what the client should send.
## Materialised endpoints: all variables are required
If `endpoint-get` shows `is_materialized: true` on the current version, the endpoint requires
**every declared variable** to be passed on each call. This is a security boundary — without
filters, a single call would return the entire pre-aggregated dataset.
Common symptom: the user's app worked when the endpoint was unmaterialised, then started
returning 400 errors after materialisation was enabled. The error message lists which variables
are missing.
Optional/partial variables on materialised endpoints are a known limitation the PostHog team plans
to lift. If requiring every variable is blocking the user's use case, send a note via the
`agent-feedback` tool — that demand signal is how the team prioritises it.
## Generating a typed client
The endpoint exposes its own OpenAPI 3.0 spec via `endpoint-openapi-spec`. Feed that into a code
generator:
| Language | Tool | Command shape |
| ---------- | ----------------------- | -------------------------------------------------------------------------------- |
| TypeScript | `@hey-api/openapi-ts` | `openapi-ts -i spec.json -o ./generated` |
| TypeScript | `openapi-generator-cli` | `openapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generated` |
| Python | `openapi-generator-cli` | `openapi-generator-cli generate -i spec.json -g python -o ./generated` |
| Go | `oapi-codegen` | `oapi-codegen -package=client spec.json > client.go` |
The generated client gives the user types for the variables payload and the response shape. Re-
generate when the endpoint's query changes (each new version may have different variables).
If the user has multiple endpoints, generate a spec per endpoint and either combine them, or
generate one client per endpoint and use them side-by-side.
## Response shape
A typical successful response:
```json
{
"results": [[...], [...]],
"columns": ["col_a", "col_b"],
"types": ["Int64", "String"],
"hasMore": false,
"name": "endpoint_name",
"endpoint_version": 4,
"endpoint_version_created_at": "2026-01-15T..."
}
```
- `results` is an array of rows; each row is an array of cell values in the order of `columns`.
- `endpoint_version` tells the client which version actually ran — useful for logging and for
pinning to a known version with `?version=N`.
For insight endpoints, the response shape depends on the query kind (`TrendsQuery`,
`LifecycleQuery`, `RetentionQuery`) — the OpenAPI spec captures the right shape for the current
version. Insight kinds that can't be materialised (e.g. `FunnelsQuery`) still return their inline
result shape.
## Calling from the PostHog CLI
For local testing, scripts, or CI, the repo's `posthog-cli` calls endpoints without hand-rolling
HTTP:
- `posthog-cli exp endpoints run` — execute an endpoint (from a local YAML definition)
- `posthog-cli exp endpoints {list,get,pull,push,diff}` — inspect endpoints, or manage them as YAML
files in version control (GitOps-style)
Auth uses the same personal API key, via `posthog-cli login` or the `POSTHOG_CLI_API_KEY` /
`POSTHOG_CLI_PROJECT_ID` / `POSTHOG_CLI_HOST` env vars. (These live under `exp` — experimental, may
change.)
## Error responses to handle
| Status | When | Handling |
| ------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| 400 | Missing required variable on a materialised endpoint, or invalid variable type | Surface the error message; fix the call |
| 401 | Missing / wrong personal API key | Check the Authorization header |
| 403 | Key lacks `endpoint:read` scope, or endpoint is in another project | Adjust key scopes |
| 404 | Endpoint name typo, or endpoint not active | Confirm name; check `is_active` |
| 429 | Rate limited — limits are per team, not per endpoint (see note below) | Exponential backoff; cache responses client-side if possible |
| 5xx | Query execution failure (ClickHouse error, timeout, etc.) | Retry with backoff. If persistent, hand off to `diagnosing-endpoint-performance` |
## Workflow
1. Confirm endpoint name. If unknown, list them with `execute-sql` on
`system.data_modeling_endpoints` (or `endpoints-get-all`).
2. `endpoint-get` to see the full shape: variables, materialisation status, query kind.
3. Decide the auth posture: personal API key on a server, never client-side.
4. If the user wants generated types, call `endpoint-openapi-spec`, hand them the spec, and
recommend a generator for their language.
5. Build a sample request payload from the variable declarations and walk through a test call.
6. Optionally call `endpoint-run` from this skill to confirm the payload works.
7. Wrap up with handling notes: the materialised-variables rule, the rate-limit shape, and
pinning to a version with `?version=N`.
## Example interaction
```text
User: "I want to call monthly_active_users from my Node.js backend.
Can you help me wire it up with types?"
Agent steps:
- endpoint-get monthly_active_users → HogQL, variables: lookback_days
(int, default 30), org_id (string, no default), is_materialized: true
- "Two things to know upfront:
1. This endpoint is materialised, so both lookback_days and org_id
must be passed on every call. Calls without them will be rejected.
2. You'll need a personal API key with endpoint:read scope. Set it
as PH_API_KEY in your server env — never ship it in client code."
- endpoint-openapi-spec monthly_active_users → returns spec
- "Here's the spec. Drop it in your repo and run:
pnpm dlx @hey-api/openapi-ts -i spec.json -o ./generated/posthog
That gives you typed client functions.
A minimum call looks like:
POST /api/projects/12345/endpoints/monthly_active_users/run
Authorization: Bearer <PH_API_KEY>
Content-Type: application/json
{ 'variables': { 'org_id': 'acme', 'lookback_days': 30 } }
The response includes columns and rows — your client will pick that
up from the generated types.
Want me to do a sample call to verify the payload works?"
```
## Important notes
- **Personal API keys are server-side only.** Never ship them in mobile apps or browser JS.
- **Re-generate the client when the query changes.** Each new endpoint version may add or
remove variables — keep types in sync by re-fetching the spec.
- **Materialised endpoints reject calls missing variables.** This is intentional. If the user
reports a 400 after materialisation was enabled, the fix is in the call, not in the endpoint.
- **Pin to a version — don't rely on "latest".** Always call with `?version=N`. Without it the
latest active version runs, so a future query edit (which cuts a new version) can silently change
a caller's results. Bump the pinned version deliberately once you've validated the new one.
- **Caching on the client side is fair game.** The endpoint already caches via
`data_freshness_seconds`, but the client can layer another cache on top for hot paths. Be
mindful of total staleness (endpoint cache + client cache).
- **Rate limits are per team, by category — not per endpoint.** Calls to non-materialised
endpoints share the team-wide API-query budget (~240/min burst, ~2400/hour sustained) with all
other query traffic; materialised endpoints draw on a separate, higher shared bucket
(~1200/min, ~12000/hour). There is no per-endpoint-name limit, so hammering one endpoint can
starve others on the same team. Heavy callers should batch where possible and back off on 429.
- **Pricing.** Calling endpoints isn't billed today, but it will be once endpoints ship alongside
the [managed warehouse](https://posthog.com/data-stack/managed-warehouse). Flag this to the user
if they're planning high-volume usage so the future cost isn't a surprise.
- **Tell PostHog what's missing.** If an error, a limit, or a missing capability gets in the way,
use the `agent-feedback` tool — it's the main signal the team uses to improve endpoints and these
tools.
© PostHog · MIT · PostHog/skills