Users

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
PATCH
GET
DELETE
GET
GET
POST
POST
POST
DELETE
← Previous pageNext page →

Retrieve users hedgehog config

Required API key scopes

user:read

Path parameters

  • uuid
    string

Example request

GET /api/users/:uuid/hedgehog_config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/

Example response

Status 200 No response body

Retrieve users hedgehog config

Required API key scopes

user:read

Path parameters

  • uuid
    string

Example request

GET /api/users/:uuid/hedgehog_config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/

Example response

Status 200 No response body

Update users hedgehog config

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • first_name
    string
  • last_name
    string
  • email
    string
  • notification_settings
    object
  • anonymize_data
    booleannull
  • allow_impersonation
    booleannull
  • toolbar_mode
  • is_staff
    boolean
  • set_current_organization
    string
  • set_current_team
    string
  • password
    string
  • current_password
    string
  • events_column_config
  • has_seen_product_intro_for
  • theme_mode
  • hedgehog_config
  • allow_sidebar_suggestions
    booleannull
  • shortcut_position
  • role_at_organization
  • passkeys_enabled_for_2fa
    booleannull
  • hide_mcp_hints
    boolean
  • ui_configuration

Example request

PATCH /api/users/:uuid/hedgehog_config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/\
	-d date_joined="string"

Example response

Status 200 No response body

Update users hedgehog config

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • first_name
    string
  • last_name
    string
  • email
    string
  • notification_settings
    object
  • anonymize_data
    booleannull
  • allow_impersonation
    booleannull
  • toolbar_mode
  • is_staff
    boolean
  • set_current_organization
    string
  • set_current_team
    string
  • password
    string
  • current_password
    string
  • events_column_config
  • has_seen_product_intro_for
  • theme_mode
  • hedgehog_config
  • allow_sidebar_suggestions
    booleannull
  • shortcut_position
  • role_at_organization
  • passkeys_enabled_for_2fa
    booleannull
  • hide_mcp_hints
    boolean
  • ui_configuration

Example request

PATCH /api/users/:uuid/hedgehog_config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/hedgehog_config/\
	-d date_joined="string"

Example response

Status 200 No response body

List all users integrations

Return the authenticated user's personal integrations of a given kind (github or slack).

The response shape varies per kind because the underlying UserIntegration rows carry different identity fields — GitHub rows expose installation_id / account / uses_shared_installation; Slack rows expose slack_user_id / slack_team_id / slack_team_name. Kind-specific destroy and start actions remain split so their distinct semantics (e.g. Slack's lack of "uninstall on last reference") stay explicit at the URL layer.

Default of kind=github is load-bearing: mobile (apps/mobile/...) and the Code SDK (packages/api-client/...) both call this endpoint without a query param today and rely on receiving GitHub rows.

Required API key scopes

user:read

Path parameters

  • uuid
    string

Query parameters

  • kind
    string
    One of: "github""slack"
  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/users/:uuid/integrations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "results": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "kind": "string",
          "installation_id": "string",
          "repository_selection": "string",
          "account": {
            "type": "string",
            "name": "string"
          },
          "github_login": "string",
          "uses_shared_installation": true,
          "created_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

List all users integrations

Return the authenticated user's personal integrations of a given kind (github or slack).

The response shape varies per kind because the underlying UserIntegration rows carry different identity fields — GitHub rows expose installation_id / account / uses_shared_installation; Slack rows expose slack_user_id / slack_team_id / slack_team_name. Kind-specific destroy and start actions remain split so their distinct semantics (e.g. Slack's lack of "uninstall on last reference") stay explicit at the URL layer.

Default of kind=github is load-bearing: mobile (apps/mobile/...) and the Code SDK (packages/api-client/...) both call this endpoint without a query param today and rely on receiving GitHub rows.

Required API key scopes

user:read

Path parameters

  • uuid
    string

Query parameters

  • kind
    string
    One of: "github""slack"
  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/users/:uuid/integrations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "results": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "kind": "string",
          "installation_id": "string",
          "repository_selection": "string",
          "account": {
            "type": "string",
            "name": "string"
          },
          "github_login": "string",
          "uses_shared_installation": true,
          "created_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

Delete users integrations github

Remove a specific GitHub installation by its installation_id.

Required API key scopes

user:write

Path parameters

  • installation_id
    string
  • uuid
    string

Example request

DELETE /api/users/:uuid/integrations/github/:installation_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/

Example response

Status 204 Integration removed.

Delete users integrations github

Remove a specific GitHub installation by its installation_id.

Required API key scopes

user:write

Path parameters

  • installation_id
    string
  • uuid
    string

Example request

DELETE /api/users/:uuid/integrations/github/:installation_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/

Example response

Status 204 Integration removed.

Retrieve users integrations github branches

List branches for a repository accessible to a personal GitHub installation.

Required API key scopes

user:read

Path parameters

  • installation_id
    string
  • uuid
    string

Query parameters

  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • repo
    string
  • search
    string
    Default:

Response


Example request

GET /api/users/:uuid/integrations/github/:installation_id/branches
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/branches/

Example response

Status 200
RESPONSE
{
  "branches": [
    "string"
  ],
  "default_branch": "string",
  "has_more": true
}

Retrieve users integrations github branches

List branches for a repository accessible to a personal GitHub installation.

Required API key scopes

user:read

Path parameters

  • installation_id
    string
  • uuid
    string

Query parameters

  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • repo
    string
  • search
    string
    Default:

Response


Example request

GET /api/users/:uuid/integrations/github/:installation_id/branches
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/branches/

Example response

Status 200
RESPONSE
{
  "branches": [
    "string"
  ],
  "default_branch": "string",
  "has_more": true
}

Retrieve users integrations github repos

List repositories accessible to a specific GitHub installation (paginated, cached).

Required API key scopes

user:read

Path parameters

  • installation_id
    string
  • uuid
    string

Query parameters

  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • search
    string
    Default:

Response


Example request

GET /api/users/:uuid/integrations/github/:installation_id/repos
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/repos/

Example response

Status 200
RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string",
      "private": true,
      "default_branch": "string",
      "language": "string",
      "pushed_at": "string",
      "archived": true,
      "can_push": true
    }
  ],
  "has_more": true
}

Retrieve users integrations github repos

List repositories accessible to a specific GitHub installation (paginated, cached).

Required API key scopes

user:read

Path parameters

  • installation_id
    string
  • uuid
    string

Query parameters

  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • search
    string
    Default:

Response


Example request

GET /api/users/:uuid/integrations/github/:installation_id/repos
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/repos/

Example response

Status 200
RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string",
      "private": true,
      "default_branch": "string",
      "language": "string",
      "pushed_at": "string",
      "archived": true,
      "can_push": true
    }
  ],
  "has_more": true
}

Create users integrations github repos refresh

Refresh repositories accessible to a specific GitHub installation.

Required API key scopes

user:write

Path parameters

  • installation_id
    string
  • uuid
    string

Response


Example request

POST /api/users/:uuid/integrations/github/:installation_id/repos/refresh
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/repos/refresh/

Example response

Status 200
RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string",
      "private": true,
      "default_branch": "string",
      "language": "string",
      "pushed_at": "string",
      "archived": true,
      "can_push": true
    }
  ]
}

Create users integrations github repos refresh

Refresh repositories accessible to a specific GitHub installation.

Required API key scopes

user:write

Path parameters

  • installation_id
    string
  • uuid
    string

Response


Example request

POST /api/users/:uuid/integrations/github/:installation_id/repos/refresh
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/:installation_id/repos/refresh/

Example response

Status 200
RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string",
      "private": true,
      "default_branch": "string",
      "language": "string",
      "pushed_at": "string",
      "archived": true,
      "can_push": true
    }
  ]
}

Create users integrations github prepare callback

Seed personal GitHub manage callback state before opening installation settings on GitHub.

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • installation_id
    string

Example request

POST /api/users/:uuid/integrations/github/prepare_callback
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/prepare_callback/\
	-d installation_id="string"

Example response

Status 204 No content

Create users integrations github prepare callback

Seed personal GitHub manage callback state before opening installation settings on GitHub.

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • installation_id
    string

Example request

POST /api/users/:uuid/integrations/github/prepare_callback
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/prepare_callback/\
	-d installation_id="string"

Example response

Status 204 No content

Create users integrations github start

Start GitHub linking: either full App install or OAuth-only (user-to-server).

**_kwargs absorbs parent_lookup_uuid from the nested /api/users/{uuid}/integrations/ router (same pattern as local_evaluation under projects).

Usually returns install_url pointing at /installations/new so the user can pick any GitHub org (new or already connected). GitHub's install page handles both cases: orgs where the app is installed show "Configure" (no admin needed), orgs where it isn't show "Install" (needs admin).

OAuth fast path: when the current project already has a team-level GitHub installation, and the user has no UserIntegration for that installation yet, we skip the org picker and redirect straight to /login/oauth/authorize so the user only authorizes themselves. connect_from is preserved for first-party clients so they return to the originating client immediately.

In both cases the response key is install_url for compatibility with callers.

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • team_id
    integernull
  • connect_from
    string

Response


Example request

POST /api/users/:uuid/integrations/github/start
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/start/\
	-d team_id=["integer","null"]

Example response

Status 200
RESPONSE
{
  "install_url": "string",
  "connect_flow": "string"
}

Create users integrations github start

Start GitHub linking: either full App install or OAuth-only (user-to-server).

**_kwargs absorbs parent_lookup_uuid from the nested /api/users/{uuid}/integrations/ router (same pattern as local_evaluation under projects).

Usually returns install_url pointing at /installations/new so the user can pick any GitHub org (new or already connected). GitHub's install page handles both cases: orgs where the app is installed show "Configure" (no admin needed), orgs where it isn't show "Install" (needs admin).

OAuth fast path: when the current project already has a team-level GitHub installation, and the user has no UserIntegration for that installation yet, we skip the org picker and redirect straight to /login/oauth/authorize so the user only authorizes themselves. connect_from is preserved for first-party clients so they return to the originating client immediately.

In both cases the response key is install_url for compatibility with callers.

Required API key scopes

user:write

Path parameters

  • uuid
    string

Request parameters

  • team_id
    integernull
  • connect_from
    string

Response


Example request

POST /api/users/:uuid/integrations/github/start
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/start/\
	-d team_id=["integer","null"]

Example response

Status 200
RESPONSE
{
  "install_url": "string",
  "connect_flow": "string"
}

Delete users integrations slack

Remove a Slack identity link by Slack user id. Idempotent and flag-agnostic — users must always be able to unlink even after the feature flag is turned off.

Required API key scopes

user:write

Path parameters

  • slack_user_id
    string
  • uuid
    string

Example request

DELETE /api/users/:uuid/integrations/slack/:slack_user_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/slack/:slack_user_id/

Example response

Status 204 Slack link removed.

Delete users integrations slack

Remove a Slack identity link by Slack user id. Idempotent and flag-agnostic — users must always be able to unlink even after the feature flag is turned off.

Required API key scopes

user:write

Path parameters

  • slack_user_id
    string
  • uuid
    string

Example request

DELETE /api/users/:uuid/integrations/slack/:slack_user_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/slack/:slack_user_id/

Example response

Status 204 Slack link removed.
← Previous pageNext page →