External Data API Reference

External Data

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`PATCH`
`POST`
`POST`
`GET`
`POST`
`POST`
`PATCH`
`POST`
`GET`
`POST`
`GET`
`POST`
`POST`
`GET`

List all environments external data sources

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Query parameters

limit
integer
offset
integer
search
string

Response

Example request

GET /api/environments/:environment_id/external_data_sources
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/".format(
        project_id=project_id
    ),
    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": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "string",
      "created_via": "web",
      "status": "string",
      "client_secret": "string",
      "account_id": "string",
      "source_type": "Ashby",
      "latest_error": "string",
      "prefix": "string",
      "description": "string",
      "access_method": "warehouse",
      "engine": "duckdb",
      "last_run_at": "string",
      "schemas": [
        {}
      ],
      "job_inputs": null,
      "revenue_analytics_config": {
        "enabled": true,
        "include_invoiceless_charges": true
      },
      "user_access_level": "string",
      "supports_webhooks": true
    }
  ]
}

Create environments external data sources

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Request parameters

source_type
payload
object
prefix
stringnull
description
stringnull
access_method
Default: warehouse
created_via
Default: api

Response

Example request

POST /api/environments/:environment_id/external_data_sources
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/environments/:environment_id/external_data_sources/\
	-d source_type=undefined,\
	-d payload="object"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"payload": "object"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "string",
  "created_via": "web",
  "status": "string",
  "client_secret": "string",
  "account_id": "string",
  "source_type": "Ashby",
  "latest_error": "string",
  "prefix": "string",
  "description": "string",
  "access_method": "warehouse",
  "engine": "duckdb",
  "last_run_at": "string",
  "schemas": [
    {}
  ],
  "job_inputs": null,
  "revenue_analytics_config": {
    "enabled": true,
    "include_invoiceless_charges": true
  },
  "user_access_level": "string",
  "supports_webhooks": true
}

Retrieve environments external data sources

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Path parameters

id
string

Response

Example request

GET /api/environments/:environment_id/external_data_sources/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "string",
  "created_via": "web",
  "status": "string",
  "client_secret": "string",
  "account_id": "string",
  "source_type": "Ashby",
  "latest_error": "string",
  "prefix": "string",
  "description": "string",
  "access_method": "warehouse",
  "engine": "duckdb",
  "last_run_at": "string",
  "schemas": [
    {}
  ],
  "job_inputs": null,
  "revenue_analytics_config": {
    "enabled": true,
    "include_invoiceless_charges": true
  },
  "user_access_level": "string",
  "supports_webhooks": true
}

Update environments external data sources

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Response

Example request

PATCH /api/environments/:environment_id/external_data_sources/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/\
	-d created_at="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"created_at": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "string",
  "created_via": "web",
  "status": "string",
  "client_secret": "string",
  "account_id": "string",
  "source_type": "Ashby",
  "latest_error": "string",
  "prefix": "string",
  "description": "string",
  "access_method": "warehouse",
  "engine": "duckdb",
  "last_run_at": "string",
  "schemas": [
    {}
  ],
  "job_inputs": null,
  "revenue_analytics_config": {
    "enabled": true,
    "include_invoiceless_charges": true
  },
  "user_access_level": "string",
  "supports_webhooks": true
}

Delete environments external data sources

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Example request

DELETE /api/environments/:environment_id/external_data_sources/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Update environments external data sources bulk update schemas

Create, Read, Update and Delete External data Sources.

Path parameters

id
string

Query parameters

limit
integer
offset
integer
search
string

Request parameters

schemas
array

Response

Example request

PATCH /api/environments/:environment_id/external_data_sources/:id/bulk_update_schemas
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/bulk_update_schemas/\
	-d schemas="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/bulk_update_schemas/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"schemas": "array"
	}
).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": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "label": "string",
      "table": {},
      "should_sync": true,
      "last_synced_at": "2019-08-24T14:15:22Z",
      "latest_error": "string",
      "incremental": true,
      "status": "string",
      "sync_type": "full_refresh",
      "incremental_field": "string",
      "incremental_field_type": "integer",
      "sync_frequency": "never",
      "sync_time_of_day": "14:15:22Z",
      "description": "string",
      "primary_key_columns": [
        "string"
      ],
      "cdc_table_mode": "consolidated"
    }
  ]
}

Create environments external data sources create webhook

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/:id/create_webhook
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/environments/:environment_id/external_data_sources/:id/create_webhook/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/create_webhook/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Create environments external data sources delete webhook

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/:id/delete_webhook
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/environments/:environment_id/external_data_sources/:id/delete_webhook/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/delete_webhook/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments external data sources jobs

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Path parameters

id
string

Example request

GET /api/environments/:environment_id/external_data_sources/:id/jobs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/jobs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/jobs/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments external data sources refresh schemas

Fetch current schema/table list from the source and create any new ExternalDataSchema rows (no data sync).

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/:id/refresh_schemas
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/environments/:environment_id/external_data_sources/:id/refresh_schemas/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/refresh_schemas/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Create environments external data sources reload

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/:id/reload
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/environments/:environment_id/external_data_sources/:id/reload/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/reload/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Update environments external data sources revenue analytics config

Update the revenue analytics configuration and return the full external data source.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

PATCH /api/environments/:environment_id/external_data_sources/:id/revenue_analytics_config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/revenue_analytics_config/\
	-d created_at="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/revenue_analytics_config/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"created_at": "string"
	}
).json()

Example response

Status 200 No response body

Create environments external data sources update webhook inputs

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Path parameters

id
string

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/:id/update_webhook_inputs
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/environments/:environment_id/external_data_sources/:id/update_webhook_inputs/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/update_webhook_inputs/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments external data sources webhook info

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Path parameters

id
string

Example request

GET /api/environments/:environment_id/external_data_sources/:id/webhook_info
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/:id/webhook_info/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/{external_data_source_id}/webhook_info/".format(
        project_id=project_id,
		external_data_source_id="<the external data source id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create environments external data sources check cdc prerequisites

Validate CDC prerequisites against a live Postgres connection.

Used by the source wizard to surface ✅/❌ checks before source creation, and by the self-managed setup popup to verify user-created publications.

Required API key scopes

external_data_source:write

Example request

POST /api/environments/:environment_id/external_data_sources/check_cdc_prerequisites
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/environments/:environment_id/external_data_sources/check_cdc_prerequisites/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/check_cdc_prerequisites/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Whether the Postgres database satisfies CDC prerequisites.

Status 400 Invalid config, disallowed host, or connection failure.

List all environments external data sources connections

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Query parameters

limit
integer
offset
integer
search
string

Response

Example request

GET /api/environments/:environment_id/external_data_sources/connections
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/connections/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/connections/".format(
        project_id=project_id
    ),
    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": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "prefix": "string",
      "engine": "duckdb"
    }
  ]
}

Create environments external data sources database schema

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Request parameters

source_type

Example request

POST /api/environments/:environment_id/external_data_sources/database_schema
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/environments/:environment_id/external_data_sources/database_schema/\
	-d source_type=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/database_schema/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200 No response body

Create environments external data sources source prefix

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:write

Request parameters

created_via
client_secret
string
account_id
string
prefix
stringnull
description
stringnull
job_inputs

Example request

POST /api/environments/:environment_id/external_data_sources/source_prefix
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/environments/:environment_id/external_data_sources/source_prefix/\
	-d client_secret="string",\
	-d account_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/source_prefix/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"client_secret": "string",
		"account_id": "string"
	}
).json()

Example response

Status 200 No response body

Retrieve environments external data sources wizard

Create, Read, Update and Delete External data Sources.

Required API key scopes

external_data_source:read

Example request

GET /api/environments/:environment_id/external_data_sources/wizard
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/external_data_sources/wizard/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/external_data_sources/wizard/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()