Proxy API Reference

Proxy

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

Endpoints

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

List all proxy records

List all reverse proxies configured for the organization. Returns proxy records along with the maximum number allowed by the current plan.

Required API key scopes

organization:read

Path parameters

organization_id
string

Example request

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

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "domain": "string",
      "target_cname": "string",
      "status": "waiting",
      "message": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": 0
    }
  ],
  "max_proxy_records": 0
}

Create proxy records

Create a new managed reverse proxy. Provide the domain you want to proxy through. The response includes the CNAME target you need to add as a DNS record. Once the CNAME is configured, the proxy will be automatically verified and provisioned.

Required API key scopes

organization:write

Path parameters

organization_id
string

Request parameters

domain
string

Response

Example request

POST /api/organizations/:organization_id/proxy_records
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/organizations/:organization_id/proxy_records/\
	-d domain="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/organizations/{organization_id}/proxy_records/".format(
        project_id=project_id,
		organization_id="<the organization id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"domain": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "domain": "string",
  "target_cname": "string",
  "status": "waiting",
  "message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": 0
}

Retrieve proxy records

Get details of a specific reverse proxy by ID. Returns the full configuration including domain, CNAME target, and current provisioning status.

Required API key scopes

organization:read

Path parameters

id
string
organization_id
string

Response

Example request

GET /api/organizations/:organization_id/proxy_records/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/proxy_records/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/organizations/{organization_id}/proxy_records/{proxy_record_id}/".format(
        project_id=project_id,
		proxy_record_id="<the proxy record id>",
		organization_id="<the organization id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "domain": "string",
  "target_cname": "string",
  "status": "waiting",
  "message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": 0
}

Delete proxy records

Delete a reverse proxy. For proxies in 'waiting', 'erroring', or 'timed_out' status, the record is deleted immediately. For active proxies, a deletion workflow is started to clean up the provisioned infrastructure.

Required API key scopes

organization:write

Path parameters

id
string
organization_id
string

Example request

DELETE /api/organizations/:organization_id/proxy_records/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/proxy_records/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/organizations/{organization_id}/proxy_records/{proxy_record_id}/".format(
        project_id=project_id,
		proxy_record_id="<the proxy record id>",
		organization_id="<the organization id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create proxy records retry

Retry provisioning a failed reverse proxy. Only available for proxies in 'erroring' or 'timed_out' status. Resets the proxy to 'waiting' status and restarts the provisioning workflow.

Path parameters

id
string
organization_id
string

Response

Example request

POST /api/organizations/:organization_id/proxy_records/:id/retry
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/organizations/:organization_id/proxy_records/:id/retry/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/organizations/{organization_id}/proxy_records/{proxy_record_id}/retry/".format(
        project_id=project_id,
		proxy_record_id="<the proxy record id>",
		organization_id="<the organization id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "domain": "string",
  "target_cname": "string",
  "status": "waiting",
  "message": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": 0
}

Proxy

Endpoints

List all proxy records

Required API key scopes

Path parameters

Example request

Example response

Status 200

Create proxy records

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 201

Retrieve proxy records

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Delete proxy records

Required API key scopes

Path parameters

Example request

Example response

Status 204 No response body

Create proxy records retry

Path parameters

Response

Example request

Example response

Status 200

Community questions