Users-2 API Reference

Users-2

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/hedgehog_config/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/hedgehog_config/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/users/{uuid}/hedgehog_config/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"date_joined": "string"
	}
).json()

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

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/users/{uuid}/hedgehog_config/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"date_joined": "string"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
          },
          "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).

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
          },
          "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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/branches/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/branches/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/repos/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/repos/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string"
    }
  ],
  "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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/repos/refresh/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string"
    }
  ]
}

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/{installation_id}/repos/refresh/".format(
        project_id=project_id,
		installation_id="<the installation id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repositories": [
    {
      "id": 0,
      "name": "string",
      "full_name": "string"
    }
  ]
}

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/prepare_callback/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"installation_id": "string"
	}
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/prepare_callback/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"installation_id": "string"
	}
).json()

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"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/start/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"team_id": [
			"integer",
			"null"
		]
	}
).json()

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).

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"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/users/{uuid}/integrations/github/start/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"team_id": [
			"integer",
			"null"
		]
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/users/{uuid}/integrations/slack/{slack_user_id}/".format(
        project_id=project_id,
		slack_user_id="<the slack user id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/users/{uuid}/integrations/slack/{slack_user_id}/".format(
        project_id=project_id,
		slack_user_id="<the slack user id>",,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 Slack link removed.

← Previous pageNext page →