PostHog Reverse Proxy API

openapi: 3.2.0
info:
  title: PostHog Reverse Proxy API
  version: 1.0.0
  description: ''
tags:
- name: Reverse Proxy
paths:
  /api/organizations/{organization_id}/proxy_records/:
    get:
      operationId: proxy_records_list
      description: List all reverse proxies configured for the organization. Returns proxy records along with the maximum number allowed by the current plan.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdPath'
      tags:
      - Reverse Proxy
      security:
      - PersonalAPIKeyAuth:
        - organization:read
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProxyRecordListResponse'
          description: ''
      x-explicit-tags:
      - reverse_proxy
      summary: Proxy records list
      x-summary-source: derived
    post:
      operationId: proxy_records_create
      description: 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.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdPath'
      tags:
      - Reverse Proxy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyRecord'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ProxyRecord'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ProxyRecord'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - organization:write
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyRecord'
          description: ''
      x-explicit-tags:
      - reverse_proxy
      summary: Proxy records create
      x-summary-source: derived
  /api/organizations/{organization_id}/proxy_records/{id}/:
    get:
      operationId: proxy_records_retrieve
      description: Get details of a specific reverse proxy by ID. Returns the full configuration including domain, CNAME target, and current provisioning status.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this proxy record.
        required: true
      - $ref: '#/components/parameters/OrganizationIdPath'
      tags:
      - Reverse Proxy
      security:
      - PersonalAPIKeyAuth:
        - organization:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyRecord'
          description: ''
      x-explicit-tags:
      - reverse_proxy
      summary: Proxy records retrieve
      x-summary-source: derived
    delete:
      operationId: proxy_records_destroy
      description: 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.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this proxy record.
        required: true
      - $ref: '#/components/parameters/OrganizationIdPath'
      tags:
      - Reverse Proxy
      security:
      - PersonalAPIKeyAuth:
        - organization:write
      responses:
        '204':
          description: No response body
      x-explicit-tags:
      - reverse_proxy
      summary: Proxy records destroy
      x-summary-source: derived
  /api/organizations/{organization_id}/proxy_records/{id}/retry/:
    post:
      operationId: proxy_records_retry_create
      description: 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.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this proxy record.
        required: true
      - $ref: '#/components/parameters/OrganizationIdPath'
      tags:
      - Reverse Proxy
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyRecord'
          description: ''
      x-explicit-tags:
      - reverse_proxy
      summary: Proxy records retry create
      x-summary-source: derived
components:
  parameters:
    OrganizationIdPath:
      in: path
      name: organization_id
      required: true
      schema:
        type: string
      description: ID of the organization you're trying to access. To find the ID of the organization, make a call to /api/organizations/.
  schemas:
    ProxyRecordStatusEnum:
      enum:
      - waiting
      - issuing
      - valid
      - warning
      - erroring
      - deleting
      - timed_out
      type: string
      description: '* `waiting` - Waiting

        * `issuing` - Issuing

        * `valid` - Valid

        * `warning` - Warning

        * `erroring` - Erroring

        * `deleting` - Deleting

        * `timed_out` - Timed Out'
    ProxyRecordListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProxyRecord'
        max_proxy_records:
          type: integer
          description: Maximum number of proxy records allowed for this organization's current plan.
      required:
      - max_proxy_records
      - results
    ProxyRecord:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the proxy record.
        domain:
          type: string
          description: The custom domain to proxy through, e.g. 'e.example.com'. Must be a valid subdomain you control.
        target_cname:
          type: string
          readOnly: true
          description: The CNAME target to add as a DNS record for your domain. Point your domain's CNAME to this value.
        status:
          allOf:
          - $ref: '#/components/schemas/ProxyRecordStatusEnum'
          readOnly: true
          description: 'Current provisioning status. Values: waiting (DNS verification pending), issuing (SSL certificate being issued), valid (proxy is live and working), warning (proxy has issues but is operational), erroring (proxy setup failed), deleting (removal in progress), timed_out (DNS verification timed out).


            * `waiting` - Waiting

            * `issuing` - Issuing

            * `valid` - Valid

            * `warning` - Warning

            * `erroring` - Erroring

            * `deleting` - Deleting

            * `timed_out` - Timed Out'
        message:
          type:
          - string
          - 'null'
          readOnly: true
          description: Human-readable status message with details about errors or warnings, if any.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When this proxy record was created.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: When this proxy record was last updated.
        created_by:
          type: integer
          readOnly: true
          description: ID of the user who created this proxy record.
      required:
      - created_at
      - created_by
      - domain
      - id
      - message
      - status
      - target_cname
      - updated_at
  securitySchemes:
    PersonalAPIKeyAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: All endpoints
  tags:
  - LLM Analytics
  - actions
  - activity_log
  - activity_logs
  - advanced_activity_logs
  - alerts
  - annotations
  - approval_policies
  - batch_exports
  - cdp
  - change_requests
  - code
  - code-invites
  - cohorts
  - comments
  - conversations
  - core
  - customer_analytics
  - customer_journeys
  - customer_profile_configs
  - dashboard_templates
  - dashboards
  - data_color_themes
  - data_modeling_jobs
  - data_warehouse
  - dataset_items
  - datasets
  - desktop_recordings
  - domains
  - early_access_feature
  - early_access_features
  - elements
  - endpoints
  - environments
  - error_tracking
  - evaluation_runs
  - evaluations
  - event_definitions
  - event_filter
  - event_schemas
  - events
  - experiment_holdouts
  - experiment_saved_metrics
  - experiments
  - exports
  - external_data_schemas
  - external_data_sources
  - feature_flags
  - file_system
  - file_system_shortcut
  - flag_value
  - groups
  - groups_types
  - health_issues
  - heatmap_screenshots
  - heatmaps
  - hog_flows
  - hog_function_templates
  - hog_functions
  - insight_variables
  - insights
  - integrations
  - invites
  - js-snippet
  - legal_documents
  - lineage
  - live_debugger_breakpoints
  - llm_analytics
  - llm_prompts
  - llm_skills
  - logs
  - managed_viewsets
  - max
  - max_tools
  - mcp_server_installations
  - mcp_servers
  - mcp_store
  - mcp_tools
  - members
  - notebooks
  - oauth_applications
  - object_media_previews
  - organizations
  - persisted_folder
  - persons
  - platform_features
  - plugin_configs
  - product_analytics
  - product_tours
  - project_secret_api_keys
  - projects
  - property_definitions
  - proxy_records
  - public_hog_function_templates
  - query
  - replay
  - reverse_proxy
  - role_external_references
  - roles
  - sandbox-environments
  - sandbox_environments
  - saved
  - schema_property_groups
  - sdk_doctor
  - session_group_summaries
  - session_recording_playlists
  - session_recordings
  - session_summaries
  - sessions
  - signals
  - subscriptions
  - surveys
  - taggers
  - task-automations
  - task-runs
  - task_automations
  - tasks
  - uploaded_media
  - user_home_settings
  - user_interviews
  - users
  - visual_review
  - warehouse_dag
  - warehouse_model_paths
  - warehouse_saved_queries
  - warehouse_saved_query_folders
  - warehouse_tables
  - warehouse_view_link
  - warehouse_view_links
  - web_analytics
  - web_experiments
  - web_vitals
  - welcome
  - workflows