Organizations

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

Endpoints

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

List all billing products

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Query parameters

  • include_plans
    boolean
    Default: false

Response


Example request

GET /api/organizations/:organization_id/billing/products
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/products/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "kind": "product",
      "key": "string",
      "usage_key": "string",
      "name": "string",
      "description": "string",
      "price_description": "string",
      "icon_key": "string",
      "image_url": "string",
      "docs_url": "string",
      "subscribed": true,
      "inclusion_only": true,
      "contact_support": true,
      "legacy_product": true,
      "free_allocation": 0,
      "usage_limit": 0,
      "unit": "string",
      "display_unit": "string",
      "display_decimals": 0,
      "display_divisor": 0,
      "tiered": true,
      "unit_amount_usd": "string",
      "tiers": [
        {
          "flat_amount_usd": "string",
          "unit_amount_usd": "string",
          "up_to": 0
        }
      ],
      "plans": [
        {
          "product_key": "string",
          "plan_key": "string",
          "name": "string",
          "description": "string",
          "image_url": "string",
          "docs_url": "string",
          "note": "string",
          "unit": "string",
          "flat_rate": true,
          "tiers": [
            {
              "flat_amount_usd": "string",
              "unit_amount_usd": "string",
              "up_to": 0
            }
          ],
          "free_allocation": 0,
          "features": [
            {
              "key": "string",
              "name": "string",
              "description": "string",
              "unit": "string",
              "limit": 0,
              "note": "string",
              "is_plan_default": true,
              "entitlement_only": true,
              "category": "string"
            }
          ],
          "included_if": "string",
          "contact_support": true,
          "unit_amount_usd": "string",
          "current_plan": true,
          "initial_billing_limit": 0
        }
      ],
      "features": [
        {
          "key": "string",
          "name": "string",
          "description": "string",
          "images": null,
          "icon_key": "string",
          "type": "string",
          "category": "string"
        }
      ],
      "trial": {
        "length": 0
      },
      "headline": "string",
      "screenshot_url": "string",
      "addons": [
        {
          "kind": "product",
          "key": "string",
          "usage_key": "string",
          "name": "string",
          "description": "string",
          "price_description": "string",
          "icon_key": "string",
          "image_url": "string",
          "docs_url": "string",
          "subscribed": true,
          "inclusion_only": true,
          "contact_support": true,
          "legacy_product": true,
          "free_allocation": 0,
          "usage_limit": 0,
          "unit": "string",
          "display_unit": "string",
          "display_decimals": 0,
          "display_divisor": 0,
          "tiered": true,
          "unit_amount_usd": "string",
          "tiers": [
            {
              "flat_amount_usd": "string",
              "unit_amount_usd": "string",
              "up_to": 0
            }
          ],
          "plans": [
            {
              "product_key": "string",
              "plan_key": "string",
              "name": "string",
              "description": "string",
              "image_url": "string",
              "docs_url": "string",
              "note": "string",
              "unit": "string",
              "flat_rate": true,
              "tiers": [
                {
                  "flat_amount_usd": "string",
                  "unit_amount_usd": "string",
                  "up_to": 0
                }
              ],
              "free_allocation": 0,
              "features": [
                {
                  "key": "string",
                  "name": "string",
                  "description": "string",
                  "unit": "string",
                  "limit": 0,
                  "note": "string",
                  "is_plan_default": true,
                  "entitlement_only": true,
                  "category": "string"
                }
              ],
              "included_if": "string",
              "contact_support": true,
              "unit_amount_usd": "string",
              "current_plan": true,
              "initial_billing_limit": 0
            }
          ],
          "features": [
            {
              "key": "string",
              "name": "string",
              "description": "string",
              "images": null,
              "icon_key": "string",
              "type": "string",
              "category": "string"
            }
          ],
          "trial": {
            "length": 0
          },
          "included_with_main_product": true,
          "included_if": "string",
          "default_unit_amount_usd": "string"
        }
      ]
    }
  ]
}

Retrieve billing products

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Path parameters

  • product_key
    string

Query parameters

  • include_plans
    boolean
    Default: false

Response


Example request

GET /api/organizations/:organization_id/billing/products/:product_key
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/products/:product_key/

Example response

Status 200
RESPONSE
{
  "kind": "product",
  "key": "string",
  "usage_key": "string",
  "name": "string",
  "description": "string",
  "price_description": "string",
  "icon_key": "string",
  "image_url": "string",
  "docs_url": "string",
  "subscribed": true,
  "inclusion_only": true,
  "contact_support": true,
  "legacy_product": true,
  "free_allocation": 0,
  "usage_limit": 0,
  "unit": "string",
  "display_unit": "string",
  "display_decimals": 0,
  "display_divisor": 0,
  "tiered": true,
  "unit_amount_usd": "string",
  "tiers": [
    {
      "flat_amount_usd": "string",
      "unit_amount_usd": "string",
      "up_to": 0
    }
  ],
  "plans": [
    {
      "product_key": "string",
      "plan_key": "string",
      "name": "string",
      "description": "string",
      "image_url": "string",
      "docs_url": "string",
      "note": "string",
      "unit": "string",
      "flat_rate": true,
      "tiers": [
        {
          "flat_amount_usd": "string",
          "unit_amount_usd": "string",
          "up_to": 0
        }
      ],
      "free_allocation": 0,
      "features": [
        {
          "key": "string",
          "name": "string",
          "description": "string",
          "unit": "string",
          "limit": 0,
          "note": "string",
          "is_plan_default": true,
          "entitlement_only": true,
          "category": "string"
        }
      ],
      "included_if": "string",
      "contact_support": true,
      "unit_amount_usd": "string",
      "current_plan": true,
      "initial_billing_limit": 0
    }
  ],
  "features": [
    {
      "key": "string",
      "name": "string",
      "description": "string",
      "images": null,
      "icon_key": "string",
      "type": "string",
      "category": "string"
    }
  ],
  "trial": {
    "length": 0
  },
  "headline": "string",
  "screenshot_url": "string",
  "addons": [
    {
      "kind": "product",
      "key": "string",
      "usage_key": "string",
      "name": "string",
      "description": "string",
      "price_description": "string",
      "icon_key": "string",
      "image_url": "string",
      "docs_url": "string",
      "subscribed": true,
      "inclusion_only": true,
      "contact_support": true,
      "legacy_product": true,
      "free_allocation": 0,
      "usage_limit": 0,
      "unit": "string",
      "display_unit": "string",
      "display_decimals": 0,
      "display_divisor": 0,
      "tiered": true,
      "unit_amount_usd": "string",
      "tiers": [
        {
          "flat_amount_usd": "string",
          "unit_amount_usd": "string",
          "up_to": 0
        }
      ],
      "plans": [
        {
          "product_key": "string",
          "plan_key": "string",
          "name": "string",
          "description": "string",
          "image_url": "string",
          "docs_url": "string",
          "note": "string",
          "unit": "string",
          "flat_rate": true,
          "tiers": [
            {
              "flat_amount_usd": "string",
              "unit_amount_usd": "string",
              "up_to": 0
            }
          ],
          "free_allocation": 0,
          "features": [
            {
              "key": "string",
              "name": "string",
              "description": "string",
              "unit": "string",
              "limit": 0,
              "note": "string",
              "is_plan_default": true,
              "entitlement_only": true,
              "category": "string"
            }
          ],
          "included_if": "string",
          "contact_support": true,
          "unit_amount_usd": "string",
          "current_plan": true,
          "initial_billing_limit": 0
        }
      ],
      "features": [
        {
          "key": "string",
          "name": "string",
          "description": "string",
          "images": null,
          "icon_key": "string",
          "type": "string",
          "category": "string"
        }
      ],
      "trial": {
        "length": 0
      },
      "included_with_main_product": true,
      "included_if": "string",
      "default_unit_amount_usd": "string"
    }
  ]
}

Retrieve billing products summary

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/products/summary
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/products/summary/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "key": "string",
      "name": "string",
      "description": "string",
      "subscribed": true,
      "addons": [
        {
          "key": "string",
          "name": "string",
          "description": "string",
          "subscribed": true
        }
      ],
      "features": [
        {
          "key": "string",
          "name": "string",
          "included": true,
          "addon_keys": [
            "string"
          ]
        }
      ]
    }
  ]
}

List all billing project

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta. Every project the organization has reported usage for, deleted ones included, so a caller knows which ids a project breakdown or a team_ids filter can name. Below full billing access the list is the projects the caller can see.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/projects
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/projects/

Example response

Status 200
RESPONSE
{
  "count": 0,
  "next": "http://example.com",
  "previous": "http://example.com",
  "results": [
    {
      "id": 0,
      "name": "string",
      "deleted": true
    }
  ]
}

Retrieve billing spend summary

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/spend
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/spend/

Example response

Status 200
RESPONSE
{
  "billing_period": {
    "current_period_start": "2019-08-24T14:15:22Z",
    "current_period_end": "2019-08-24T14:15:22Z",
    "interval": "month"
  },
  "usage_reported_through": "2019-08-24",
  "current_total_amount_usd": "string",
  "current_total_amount_usd_after_discount": "string",
  "products": [
    {
      "kind": "product",
      "key": "string",
      "usage_key": "string",
      "current_amount_usd": "string",
      "current_amount_usd_before_addons": "string",
      "tier_spend": [
        {
          "up_to": 0,
          "current_amount_usd": "string"
        }
      ],
      "addons": [
        {
          "kind": "product",
          "key": "string",
          "usage_key": "string",
          "current_amount_usd": "string",
          "current_amount_usd_before_addons": "string",
          "tier_spend": [
            {
              "up_to": 0,
              "current_amount_usd": "string"
            }
          ]
        }
      ]
    }
  ]
}

Retrieve billing spend export

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Query parameters

  • breakdowns
    string | null
  • end_date
    string | null
  • interval
    string | null
  • start_date
    string | null
  • team_ids
    string | null
  • top_projects
    integer | null
  • usage_types
    string | null

Example request

GET /api/organizations/:organization_id/billing/spend/export
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/spend/export/

Example response

Status 200

Retrieve billing spend timeseries

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Query parameters

  • breakdowns
    string | null
  • cursor
    string | null
  • end_date
    string | null
  • interval
    string | null
  • limit
    integer | null
  • start_date
    string | null
  • team_ids
    string | null
  • top_projects
    integer | null
  • usage_types
    string | null

Response


Example request

GET /api/organizations/:organization_id/billing/spend/timeseries
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/spend/timeseries/

Example response

Status 200
RESPONSE
{
  "count": 0,
  "next": "http://example.com",
  "previous": "http://example.com",
  "results": [
    {
      "id": 0,
      "label": "string",
      "data": [
        0.1
      ],
      "dates": [
        "string"
      ],
      "breakdown_type": "type",
      "breakdown_value": null
    }
  ]
}

Retrieve billing subscription

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/subscription
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/subscription/

Example response

Status 200
RESPONSE
{
  "customer_id": "string",
  "has_active_subscription": true,
  "subscription_level": "string",
  "billing_plan": "string",
  "billing_provider": "stripe",
  "is_annual_plan_customer": true,
  "billing_period": {
    "current_period_start": "2019-08-24T14:15:22Z",
    "current_period_end": "2019-08-24T14:15:22Z",
    "interval": "month"
  },
  "trial": {
    "type": "string",
    "status": "string",
    "target": "string",
    "expires_at": "2019-08-24T14:15:22Z"
  },
  "free_trial_until": "2019-08-24T14:15:22Z",
  "discount_percent": 0,
  "discount_amount_usd": "string",
  "amount_off_expires_at": "2019-08-24T14:15:22Z",
  "startup_program_label": "string",
  "startup_program_label_previous": "string",
  "billing_portal_url": "http://example.com",
  "invoices_url": "http://example.com",
  "license": {
    "plan": "string"
  },
  "billing_managed_by_partner": {
    "partner_name": "string"
  }
}

Retrieve billing usage summary

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/usage
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/usage/

Example response

Status 200
RESPONSE
{
  "billing_period": {
    "current_period_start": "2019-08-24T14:15:22Z",
    "current_period_end": "2019-08-24T14:15:22Z",
    "interval": "month"
  },
  "usage_reported_through": "2019-08-24",
  "usage_summary": [
    {
      "usage_key": "string",
      "usage": 0,
      "limit": 0,
      "todays_usage": 0,
      "quota_limited_until": "2019-08-24T14:15:22Z",
      "quota_limiting_suspended_until": "2019-08-24T14:15:22Z"
    }
  ],
  "products": [
    {
      "kind": "product",
      "key": "string",
      "usage_key": "string",
      "current_usage": 0,
      "usage_limit": 0,
      "has_exceeded_limit": true,
      "usage_ratio": 0.1,
      "tier_usage": [
        {
          "up_to": 0,
          "current_usage": 0
        }
      ],
      "addons": [
        {
          "kind": "product",
          "key": "string",
          "usage_key": "string",
          "current_usage": 0,
          "usage_limit": 0,
          "has_exceeded_limit": true,
          "usage_ratio": 0.1,
          "tier_usage": [
            {
              "up_to": 0,
              "current_usage": 0
            }
          ]
        }
      ]
    }
  ]
}

Retrieve billing usage export

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Query parameters

  • breakdowns
    string | null
  • end_date
    string | null
  • interval
    string | null
  • start_date
    string | null
  • team_ids
    string | null
  • top_projects
    integer | null
  • usage_types
    string | null

Example request

GET /api/organizations/:organization_id/billing/usage/export
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/usage/export/

Example response

Status 200

Retrieve billing usage status

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Response


Example request

GET /api/organizations/:organization_id/billing/usage/status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/usage/status/

Example response

Status 200
RESPONSE
{
  "billing_period": {
    "current_period_start": "2019-08-24T14:15:22Z",
    "current_period_end": "2019-08-24T14:15:22Z",
    "interval": "month"
  },
  "usage_reported_through": "2019-08-24",
  "products": [
    {
      "kind": "product",
      "key": "string",
      "usage_key": "string",
      "usage_limit": 0,
      "has_exceeded_limit": true,
      "approaching_limit": true,
      "quota_limited_until": "2019-08-24T14:15:22Z",
      "quota_limiting_suspended_until": "2019-08-24T14:15:22Z",
      "addons": [
        {
          "kind": "product",
          "key": "string",
          "usage_key": "string",
          "usage_limit": 0,
          "has_exceeded_limit": true,
          "approaching_limit": true,
          "quota_limited_until": "2019-08-24T14:15:22Z",
          "quota_limiting_suspended_until": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

Retrieve billing usage timeseries

In beta: the organization billing API is behind the organization-billing-api feature flag and answers 403 without it, so ask support for access. Its shapes may change while it is in beta.

Required API key scopes

billing:read

Query parameters

  • breakdowns
    string | null
  • cursor
    string | null
  • end_date
    string | null
  • interval
    string | null
  • limit
    integer | null
  • start_date
    string | null
  • team_ids
    string | null
  • top_projects
    integer | null
  • usage_types
    string | null

Response


Example request

GET /api/organizations/:organization_id/billing/usage/timeseries
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/billing/usage/timeseries/

Example response

Status 200
RESPONSE
{
  "count": 0,
  "next": "http://example.com",
  "previous": "http://example.com",
  "results": [
    {
      "id": 0,
      "label": "string",
      "data": [
        0.1
      ],
      "dates": [
        "string"
      ],
      "breakdown_type": "type",
      "breakdown_value": null
    }
  ]
}

List all cimd verification tokens

Manage CIMD verification tokens for an organization.

A partner embeds the plaintext token in their CIMD metadata document as verification_token inside the com.posthog object (the legacy top-level posthog_verification_token field still works as a fallback). When PostHog fetches the metadata, matching the token links the partner app to this organization and grants a higher default rate limit for account provisioning.

Each token is scoped at creation to the one cimd_url it will be published at, and verifies nowhere else. Two organizations may name the same URL; only the one whose token is actually served there verifies, so claiming a URL cannot be used to block a partner from verifying theirs.

The plaintext value is only available on creation; we store a hash.

Required API key scopes

organization:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/organizations/:organization_id/cimd_verification_tokens
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/cimd_verification_tokens/

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",
      "label": "string",
      "cimd_url": "string",
      "mask_value": "string",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create cimd verification tokens

Manage CIMD verification tokens for an organization.

A partner embeds the plaintext token in their CIMD metadata document as verification_token inside the com.posthog object (the legacy top-level posthog_verification_token field still works as a fallback). When PostHog fetches the metadata, matching the token links the partner app to this organization and grants a higher default rate limit for account provisioning.

Each token is scoped at creation to the one cimd_url it will be published at, and verifies nowhere else. Two organizations may name the same URL; only the one whose token is actually served there verifies, so claiming a URL cannot be used to block a partner from verifying theirs.

The plaintext value is only available on creation; we store a hash.

Required API key scopes

organization:write

Request parameters

  • label
    string
  • cimd_url
    string

Response


Example request

POST /api/organizations/:organization_id/cimd_verification_tokens
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/cimd_verification_tokens/\
	-d label="string",\
	-d cimd_url="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "label": "string",
  "cimd_url": "string",
  "mask_value": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "last_used_at": "2019-08-24T14:15:22Z",
  "value": "string"
}

Retrieve cimd verification tokens

Manage CIMD verification tokens for an organization.

A partner embeds the plaintext token in their CIMD metadata document as verification_token inside the com.posthog object (the legacy top-level posthog_verification_token field still works as a fallback). When PostHog fetches the metadata, matching the token links the partner app to this organization and grants a higher default rate limit for account provisioning.

Each token is scoped at creation to the one cimd_url it will be published at, and verifies nowhere else. Two organizations may name the same URL; only the one whose token is actually served there verifies, so claiming a URL cannot be used to block a partner from verifying theirs.

The plaintext value is only available on creation; we store a hash.

Required API key scopes

organization:read

Path parameters

  • id
    string

Response


Example request

GET /api/organizations/:organization_id/cimd_verification_tokens/: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/cimd_verification_tokens/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "label": "string",
  "cimd_url": "string",
  "mask_value": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "last_used_at": "2019-08-24T14:15:22Z"
}

Update cimd verification tokens

Manage CIMD verification tokens for an organization.

A partner embeds the plaintext token in their CIMD metadata document as verification_token inside the com.posthog object (the legacy top-level posthog_verification_token field still works as a fallback). When PostHog fetches the metadata, matching the token links the partner app to this organization and grants a higher default rate limit for account provisioning.

Each token is scoped at creation to the one cimd_url it will be published at, and verifies nowhere else. Two organizations may name the same URL; only the one whose token is actually served there verifies, so claiming a URL cannot be used to block a partner from verifying theirs.

The plaintext value is only available on creation; we store a hash.

Required API key scopes

organization:write

Path parameters

  • id
    string

Request parameters

  • cimd_url
    string

Response


Example request

PATCH /api/organizations/:organization_id/cimd_verification_tokens/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/cimd_verification_tokens/:id/\
	-d cimd_url="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "label": "string",
  "cimd_url": "string",
  "mask_value": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "last_used_at": "2019-08-24T14:15:22Z"
}

Delete cimd verification tokens

Manage CIMD verification tokens for an organization.

A partner embeds the plaintext token in their CIMD metadata document as verification_token inside the com.posthog object (the legacy top-level posthog_verification_token field still works as a fallback). When PostHog fetches the metadata, matching the token links the partner app to this organization and grants a higher default rate limit for account provisioning.

Each token is scoped at creation to the one cimd_url it will be published at, and verifies nowhere else. Two organizations may name the same URL; only the one whose token is actually served there verifies, so claiming a URL cannot be used to block a partner from verifying theirs.

The plaintext value is only available on creation; we store a hash.

Required API key scopes

organization:write

Path parameters

  • id
    string

Example request

DELETE /api/organizations/:organization_id/cimd_verification_tokens/: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/cimd_verification_tokens/:id/

Example response

Status 204 No response body

List all cross project dashboards

Dashboards the organization owns, holding insights from one or more projects.

Required API key scopes

cross_project_dashboard:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/organizations/:organization_id/cross_project_dashboards
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/cross_project_dashboards/

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",
      "description": "string",
      "filters": null,
      "tile_count": 0,
      "project_count": 0,
      "created_by": {
        "id": 0,
        "first_name": "string",
        "email": "user@example.com"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create cross project dashboards

Dashboards the organization owns, holding insights from one or more projects.

Required API key scopes

cross_project_dashboard:write

Request parameters

  • name
    string
  • description
    string
    Default:
  • filters

Response


Example request

POST /api/organizations/:organization_id/cross_project_dashboards
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/cross_project_dashboards/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "",
  "filters": null,
  "tiles": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": 0,
      "insight_id": 0,
      "layouts": null,
      "color": "string",
      "filters_overrides": null
    }
  ],
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

List all cross project dashboards tiles

Tiles on one cross-project dashboard, edited one at a time.

Writes are per tile rather than a whole-set replace, so two people editing the same dashboard cannot overwrite each other's tiles.

Required API key scopes

cross_project_dashboard:read

Path parameters

  • dashboard_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/organizations/:organization_id/cross_project_dashboards/:dashboard_id/tiles
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/organizations/:organization_id/cross_project_dashboards/:dashboard_id/tiles/

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",
      "project_id": 0,
      "insight_id": 0,
      "layouts": null,
      "color": "string",
      "filters_overrides": null
    }
  ]
}
← Previous pageNext page →