Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

10.2 KB
Raw Blame
/**
 * Auto-generated from the Django backend OpenAPI schema.
 * To modify these types, update the Django serializers or views, then run:
 *   hogli build:openapi
 * Questions or issues? #team-devex on Slack
 *
 * PostHog API - generated
 * OpenAPI spec version: 1.0.0
 */
/**
 * * `USR` - user
 * * `GIT` - GitHub
 */
export type AnnotationCreationTypeEnumApi =
    (typeof AnnotationCreationTypeEnumApi)[keyof typeof AnnotationCreationTypeEnumApi]

export const AnnotationCreationTypeEnumApi = {
    Usr: 'USR',
    Git: 'GIT',
} as const

/**
 * * `engineering` - Engineering
 * * `data` - Data
 * * `product` - Product Management
 * * `founder` - Founder
 * * `leadership` - Leadership
 * * `marketing` - Marketing
 * * `sales` - Sales / Success
 * * `student` - Student
 * * `other` - Other
 */
export type RoleAtOrganizationEnumApi = (typeof RoleAtOrganizationEnumApi)[keyof typeof RoleAtOrganizationEnumApi]

export const RoleAtOrganizationEnumApi = {
    Engineering: 'engineering',
    Data: 'data',
    Product: 'product',
    Founder: 'founder',
    Leadership: 'leadership',
    Marketing: 'marketing',
    Sales: 'sales',
    Student: 'student',
    Other: 'other',
} as const

export type BlankEnumApi = (typeof BlankEnumApi)[keyof typeof BlankEnumApi]

export const BlankEnumApi = {
    '': '',
} as const

/**
 * @nullable
 */
export type UserBasicApiHedgehogConfig = { [key: string]: unknown } | null

export interface UserBasicApi {
    readonly id: number
    readonly uuid: string
    /**
     * @maxLength 200
     * @nullable
     */
    distinct_id?: string | null
    /** @maxLength 150 */
    first_name?: string
    /** @maxLength 150 */
    last_name?: string
    /** @maxLength 254 */
    email: string
    /** @nullable */
    is_email_verified?: boolean | null
    /** @nullable */
    readonly hedgehog_config: UserBasicApiHedgehogConfig
    role_at_organization?: RoleAtOrganizationEnumApi | BlankEnumApi | null
}

/**
 * * `dashboard_item` - insight
 * * `dashboard` - dashboard
 * * `project` - project
 * * `organization` - organization
 * * `recording` - recording
 */
export type AnnotationScopeEnumApi = (typeof AnnotationScopeEnumApi)[keyof typeof AnnotationScopeEnumApi]

export const AnnotationScopeEnumApi = {
    DashboardItem: 'dashboard_item',
    Dashboard: 'dashboard',
    Project: 'project',
    Organization: 'organization',
    Recording: 'recording',
} as const

export interface AnnotationApi {
    readonly id: number
    /**
     * Annotation text shown on charts to describe the change, release, or incident.
     * @maxLength 8192
     * @nullable
     */
    content?: string | null
    /**
     * When this annotation happened (ISO 8601 timestamp). Used to position it on charts.
     * @nullable
     */
    date_marker?: string | null
    /** Who created this annotation. Use `USR` for user-created notes and `GIT` for bot/deployment notes.
     *
     * * `USR` - user
     * * `GIT` - GitHub */
    creation_type?: AnnotationCreationTypeEnumApi
    /**
     * Optional insight ID to attach this annotation to. Must belong to the current project.
     * @nullable
     */
    dashboard_item?: number | null
    /**
     * Optional dashboard ID to attach this annotation to. Must belong to the current project.
     * @nullable
     */
    dashboard_id?: number | null
    /** @nullable */
    readonly dashboard_name: string | null
    /** @nullable */
    readonly insight_short_id: string | null
    /** @nullable */
    readonly insight_name: string | null
    /** @nullable */
    readonly insight_derived_name: string | null
    readonly created_by: UserBasicApi
    /** @nullable */
    readonly created_at: string | null
    readonly updated_at: string
    /** Soft-delete flag. Set to true to hide the annotation, or false to restore it. */
    deleted?: boolean
    /** Annotation visibility scope: `project`, `organization`, `dashboard`, or `dashboard_item`. `recording` is deprecated and rejected.
     *
     * * `dashboard_item` - insight
     * * `dashboard` - dashboard
     * * `project` - project
     * * `organization` - organization
     * * `recording` - recording */
    scope?: AnnotationScopeEnumApi
    /**
     * Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.
     * @maxLength 16
     * @nullable
     */
    emoji?: string | null
    /**
     * When true, the annotation is hidden from the PostHog UI (charts and the annotations list) but still readable over the API and MCP. Use for high-frequency markers like deployments that would otherwise crowd the UI. Null (the default) means the annotation is shown.
     * @nullable
     */
    hidden_in_user_interface?: boolean | null
}

export interface PaginatedAnnotationListApi {
    count: number
    /** @nullable */
    next?: string | null
    /** @nullable */
    previous?: string | null
    results: AnnotationApi[]
}

export interface PatchedAnnotationApi {
    readonly id?: number
    /**
     * Annotation text shown on charts to describe the change, release, or incident.
     * @maxLength 8192
     * @nullable
     */
    content?: string | null
    /**
     * When this annotation happened (ISO 8601 timestamp). Used to position it on charts.
     * @nullable
     */
    date_marker?: string | null
    /** Who created this annotation. Use `USR` for user-created notes and `GIT` for bot/deployment notes.
     *
     * * `USR` - user
     * * `GIT` - GitHub */
    creation_type?: AnnotationCreationTypeEnumApi
    /**
     * Optional insight ID to attach this annotation to. Must belong to the current project.
     * @nullable
     */
    dashboard_item?: number | null
    /**
     * Optional dashboard ID to attach this annotation to. Must belong to the current project.
     * @nullable
     */
    dashboard_id?: number | null
    /** @nullable */
    readonly dashboard_name?: string | null
    /** @nullable */
    readonly insight_short_id?: string | null
    /** @nullable */
    readonly insight_name?: string | null
    /** @nullable */
    readonly insight_derived_name?: string | null
    readonly created_by?: UserBasicApi
    /** @nullable */
    readonly created_at?: string | null
    readonly updated_at?: string
    /** Soft-delete flag. Set to true to hide the annotation, or false to restore it. */
    deleted?: boolean
    /** Annotation visibility scope: `project`, `organization`, `dashboard`, or `dashboard_item`. `recording` is deprecated and rejected.
     *
     * * `dashboard_item` - insight
     * * `dashboard` - dashboard
     * * `project` - project
     * * `organization` - organization
     * * `recording` - recording */
    scope?: AnnotationScopeEnumApi
    /**
     * Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.
     * @maxLength 16
     * @nullable
     */
    emoji?: string | null
    /**
     * When true, the annotation is hidden from the PostHog UI (charts and the annotations list) but still readable over the API and MCP. Use for high-frequency markers like deployments that would otherwise crowd the UI. Null (the default) means the annotation is shown.
     * @nullable
     */
    hidden_in_user_interface?: boolean | null
}

/**
 * * `feature_flag` - Feature flag
 * * `experiment` - Experiment
 * * `release` - Release
 * * `annotation` - Annotation
 */
export type ChangeKindEnumApi = (typeof ChangeKindEnumApi)[keyof typeof ChangeKindEnumApi]

export const ChangeKindEnumApi = {
    FeatureFlag: 'feature_flag',
    Experiment: 'experiment',
    Release: 'release',
    Annotation: 'annotation',
} as const

export interface ChangeFeedItemApi {
    /** The source of the change.
     *
     * * `feature_flag` - Feature flag
     * * `experiment` - Experiment
     * * `release` - Release
     * * `annotation` - Annotation */
    kind: ChangeKindEnumApi
    /** When the change happened. For annotations, this is the time the annotation marks. */
    timestamp: string
    /** ID of the changed object: the feature flag, experiment, release, or annotation ID. */
    item_id: string
    /**
     * Display name: the flag key, experiment name, release version, or annotation text.
     * @nullable
     */
    name: string | null
    /** What happened, for example `created`, `updated`, `deleted`, `released`, or `annotated`. */
    activity: string
    /** For flag and experiment updates, the names of the fields that changed. Empty for other kinds. */
    changed_fields: string[]
    /**
     * For releases, the project or service the release belongs to. Null for other kinds.
     * @nullable
     */
    service: string | null
    /**
     * Name or email of the person who made the change. Null for automated changes.
     * @nullable
     */
    actor_name: string | null
}

export interface ChangeFeedApi {
    /** Changes in the time window, newest first. */
    results: ChangeFeedItemApi[]
    /** True when the window holds more changes than `limit`. Narrow the window to see the rest. */
    has_more: boolean
}

export type AnnotationsListParams = {
    /**
     * Number of results to return per page.
     * @maximum 1000
     */
    limit?: number
    /**
     * The initial index from which to return the results.
     */
    offset?: number
    /**
     * A search term.
     */
    search?: string
}

export type ChangeFeedListParams = {
    /**
     * Start of the time window (inclusive), ISO 8601. Defaults to 24 hours before `date_to`.
     */
    date_from?: string
    /**
     * End of the time window (inclusive), ISO 8601. Defaults to now.
     */
    date_to?: string
    /**
     * Return only these kinds of change. Omit to return every kind. Use `feature_flag` and `experiment` to see configuration edits without releases and annotations.
     */
    kinds?: ChangeFeedListKindsItem[]
    /**
     * Maximum number of changes to return, newest first. Defaults to 100, at most 500.
     * @minimum 1
     * @maximum 500
     */
    limit?: number
}

/**
 * * `feature_flag` - Feature flag
 * * `experiment` - Experiment
 * * `release` - Release
 * * `annotation` - Annotation
 */
export type ChangeFeedListKindsItem = (typeof ChangeFeedListKindsItem)[keyof typeof ChangeFeedListKindsItem]

export const ChangeFeedListKindsItem = {
    FeatureFlag: 'feature_flag',
    Experiment: 'experiment',
    Release: 'release',
    Annotation: 'annotation',
} as const