Adopting generated API types

1. High-level object API (most common)

Domain-specific convenience methods on the api object:

api.surveys.get(id)
api.surveys.create(data)
api.dashboards.list()
api.cohorts.update(id, data)
api.actions.create(data)

These are the most widely used pattern — every entity has its own namespace with CRUD plus custom methods (e.g., api.surveys.getResponsesCount(), api.dashboards.streamTiles()).

2. Raw HTTP methods with manual URLs

api.get<SomeType>(`api/projects/${id}/surveys/`)
api.create<SomeType>(`api/projects/${id}/surveys/`, data)
api.update<SomeType>(url, data)
api.put<SomeType>(url, data)
api.delete(url)

3. ApiRequest builder (fluent URL construction)

const url = new ApiRequest().surveys().assembleFullUrl()
const response = await api.get(url)

// or directly:
await new ApiRequest().survey(surveyId).withAction('summarize_responses').create({ data })

All three patterns should be replaced with generated functions where available.

When to use

• Touching a file that calls api.<entity>.<method>() (e.g., api.surveys.get())
• Touching a file that calls api.get<T>(...), api.create<T>(...), etc.
• Touching a file that uses new ApiRequest() to build URLs
• Touching a file that imports handwritten interfaces from ~/types for API response shapes
• Cleaning up frontend code after backend serializer improvements

Step-by-step workflow

1. Identify what the manual call does

Look at the existing call and extract:

• HTTP method — GET, POST, PUT, PATCH, DELETE
• Entity and action — what resource, what operation
• Type parameter — the handwritten type used for the response

2. Find the generated equivalent

Generated function names follow the {resource}{Action} convention:

surveysList          — GET    /api/projects/{id}/surveys/
surveysCreate        — POST   /api/projects/{id}/surveys/
surveysRetrieve      — GET    /api/projects/{id}/surveys/{id}/
surveysPartialUpdate — PATCH  /api/projects/{id}/surveys/{id}/
surveysDestroy       — DELETE /api/projects/{id}/surveys/{id}/

Where to search:

• Core endpoints: frontend/src/generated/core/api.ts
• Product endpoints: products/<product>/frontend/generated/api.ts

Search strategies:

1. Grep for the entity name in the generated api.ts files
2. Search by the get*Url helper functions — every generated function has a URL builder above it
3. Search api.schemas.ts for the type name with Api suffix

If no generated function exists, the backend endpoint may lack @extend_schema or @validated_request. Fix the backend first using the improving-drf-endpoints skill, then run hogli build:openapi.

Custom actions (like api.surveys.summarize_responses()) may not have generated equivalents if the backend @action lacks @extend_schema. Check generated files first; if missing, fix the backend.

3. Check type compatibility

Compare the handwritten type with the generated Api type. Key differences:

• readonly modifiers — generated types mark read-only fields
• Optional vs required — generated types reflect required= precisely
• Nullability — null types are explicit
• Extra fields — generated types may include fields the handwritten type omits

See type-compatibility.md for details.

4. Replace the call

See migration-patterns.md for detailed before/after examples covering:

• High-level object API (api.surveys.get() → surveysRetrieve())
• Raw HTTP methods (api.get<T>(url) → generated function)
• ApiRequest builder → generated function
• Paginated list calls
• Create/update with request bodies
• Delete calls
• Kea logic loaders and listeners
• Calls with abort signals

5. Replace the type at usage sites

Update downstream references from the handwritten type to the generated one:

// Before
function renderSurvey(survey: Survey): JSX.Element { ... }

// After
function renderSurvey(survey: SurveyApi): JSX.Element { ... }

6. Clean up dead types

After migrating all usages of a handwritten type:

1. Remove the type definition from ~/types or the local file
2. Remove unused imports
3. Run pnpm --filter=@posthog/frontend typescript:check to verify no breakage

Decision guide

Import conventions

// Core generated functions — import from api.ts
import { domainsList, domainsCreate, domainsRetrieve } from '~/generated/core/api'

// Core generated types — import type from api.schemas.ts
import type { OrganizationDomainApi } from '~/generated/core/api.schemas'

// Product generated functions — NO tilde prefix, use 'products/' path
import { surveysList, surveysRetrieve } from 'products/surveys/frontend/generated/api'
import type { SurveyApi } from 'products/surveys/frontend/generated/api.schemas'

// Within a product, relative imports also work
import { logsAlertsCreate } from '../generated/api'
import type { LogsAlertConfigurationApi } from '../generated/api.schemas'

Path rules:

• Core: ~/generated/core/... (tilde prefix)
• Products from outside: products/<product>/frontend/generated/... (no tilde)
• Products from inside: relative ../generated/... or ./generated/...

Use import type for types to enable proper tree-shaking.

How generated functions work under the hood

Generated functions wrap the same api module via api-orval-mutator.ts:

surveysList(projectId, params)
  → apiMutator(url, { method: 'GET' })
    → api.get(url)

Switching to generated functions does not change HTTP behavior — same cookies, same CSRF, same error handling. The only difference is type safety and URL construction.

Verifying the migration

1. TypeScript check: pnpm --filter=@posthog/frontend typescript:check
2. Grep for leftover manual types: search for the old type name across the codebase
3. Run relevant tests: hogli test <test_file>

Related

• Backend side: use improving-drf-endpoints to fix serializers that produce poor types
• Type system docs: docs/published/handbook/engineering/type-system.md
• API mutator: frontend/src/lib/api-orval-mutator.ts
• Regenerate types: hogli build:openapi