fix(posthog): validate integration against live API docs, add self-hosted support + CRUD coverage

apps/sim/tools/error-extractors.ts

@@ -243,6 +243,17 @@ const ERROR_EXTRACTORS: ErrorExtractorConfig[] = [
       return undefined
     },
   },
+  {
+    id: 'posthog-errors',
+    description: 'PostHog API error format with type/code/detail/attr fields',
+    examples: ['PostHog API'],
+    extract: (errorInfo) => {
+      const detail = errorInfo?.data?.detail
+      if (typeof detail !== 'string' || !detail.trim()) return undefined
+      const attr = errorInfo?.data?.attr
+      return typeof attr === 'string' && attr ? `${detail} (${attr})` : detail
+    },
+  },
   {
     id: 'plain-text-data',
     description: 'Plain text error response',
@@ -320,6 +331,7 @@ export const ErrorExtractorId = {
   SOAP_FAULT: 'soap-fault',
   OAUTH_ERROR_DESCRIPTION: 'oauth-error-description',
   NESTED_ERROR_OBJECT: 'nested-error-object',
+  POSTHOG_ERRORS: 'posthog-errors',
   PLAIN_TEXT_DATA: 'plain-text-data',
   HTTP_STATUS_TEXT: 'http-status-text',
 } as const

apps/sim/tools/posthog/batch_events.ts

@@ -1,8 +1,11 @@
+import { getErrorMessage } from '@sim/utils/errors'
+import { getPostHogIngestBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export interface PostHogBatchEventsParams {
   projectApiKey: string
   region?: 'us' | 'eu'
+  host?: string
   batch: string
 }
 
@@ -35,6 +38,13 @@ export const batchEventsTool: ToolConfig<PostHogBatchEventsParams, PostHogBatchE
       description: 'PostHog region: us (default) or eu',
       default: 'us',
     },
+    host: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description:
+        'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+    },
     batch: {
       type: 'string',
       required: true,
@@ -46,49 +56,44 @@ export const batchEventsTool: ToolConfig<PostHogBatchEventsParams, PostHogBatchE
 
   request: {
     url: (params) => {
-      const baseUrl =
-        params.region === 'eu' ? 'https://eu.i.posthog.com' : 'https://us.i.posthog.com'
+      const baseUrl = getPostHogIngestBaseUrl(params.region, params.host)
       return `${baseUrl}/batch/`
     },
     method: 'POST',
     headers: (params) => ({
       'Content-Type': 'application/json',
     }),
     body: (params) => {
-      let batch: any[]
+      let batch: unknown
       try {
         batch = JSON.parse(params.batch)
-      } catch (e) {
-        batch = []
+      } catch (error) {
+        throw new Error(`Invalid batch JSON: ${getErrorMessage(error)}`)
+      }
+      if (!Array.isArray(batch)) {
+        throw new Error('batch must be a JSON array of events')
       }
 
       return {
         api_key: params.projectApiKey,
-        batch: batch,
+        batch,
       }
     },
   },
 
-  transformResponse: async (response: Response) => {
-    if (response.ok) {
-      const data = await response.json()
-      return {
-        success: true,
-        output: {
-          status: 'Batch events captured successfully',
-          events_processed: data.status === 1 ? JSON.parse(data.batch || '[]').length : 0,
-        },
-      }
-    }
+  transformResponse: async (response: Response, params) => {
+    const data = await response.json()
+    const eventsProcessed = params ? (JSON.parse(params.batch) as unknown[]).length : 0
+    const success = data.status === 1
 
-    const error = await response.text()
     return {
-      success: false,
+      success,
       output: {
-        status: 'Failed to capture batch events',
-        events_processed: 0,
+        status: success
+          ? 'Batch events captured successfully'
+          : `Batch events capture failed (status: ${data.status})`,
+        events_processed: success ? eventsProcessed : 0,
       },
-      error: error || 'Unknown error occurred',
     }
   },
 

apps/sim/tools/posthog/capture_event.ts

@@ -1,8 +1,11 @@
+import { getErrorMessage } from '@sim/utils/errors'
+import { getPostHogIngestBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export interface PostHogCaptureEventParams {
   projectApiKey: string
   region?: 'us' | 'eu'
+  host?: string
   event: string
   distinctId: string
   properties?: string
@@ -38,6 +41,13 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
         description: 'PostHog region: us (default) or eu',
         default: 'us',
       },
+      host: {
+        type: 'string',
+        required: false,
+        visibility: 'user-only',
+        description:
+          'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+      },
       event: {
         type: 'string',
         required: true,
@@ -69,8 +79,7 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
 
     request: {
       url: (params) => {
-        const baseUrl =
-          params.region === 'eu' ? 'https://eu.i.posthog.com' : 'https://us.i.posthog.com'
+        const baseUrl = getPostHogIngestBaseUrl(params.region, params.host)
         return `${baseUrl}/capture/`
       },
       method: 'POST',
@@ -87,8 +96,8 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
         if (params.properties) {
           try {
             body.properties = JSON.parse(params.properties)
-          } catch (e) {
-            body.properties = {}
+          } catch (error) {
+            throw new Error(`Invalid properties JSON: ${getErrorMessage(error)}`)
           }
         }
 
@@ -101,22 +110,16 @@ export const captureEventTool: ToolConfig<PostHogCaptureEventParams, PostHogCapt
     },
 
     transformResponse: async (response: Response) => {
-      if (response.ok) {
-        return {
-          success: true,
-          output: {
-            status: 'Event captured successfully',
-          },
-        }
-      }
+      const data = await response.json()
+      const success = data.status === 1
 
-      const error = await response.text()
       return {
-        success: false,
+        success,
         output: {
-          status: 'Failed to capture event',
+          status: success
+            ? 'Event captured successfully'
+            : `Event capture failed (status: ${data.status})`,
         },
-        error: error || 'Unknown error occurred',
       }
     },
 

apps/sim/tools/posthog/create_annotation.ts

@@ -1,14 +1,16 @@
+import { getPostHogAppBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 interface PostHogCreateAnnotationParams {
   apiKey: string
   projectId: string
   region: string
+  host?: string
   content: string
   date_marker: string
   scope?: string
   dashboard_item?: string
-  insight_short_id?: string
+  dashboard_id?: string
 }
 
 interface PostHogCreateAnnotationResponse {
@@ -21,6 +23,7 @@ interface PostHogCreateAnnotationResponse {
     updated_at: string
     created_by: Record<string, any> | null
     dashboard_item: number | null
+    dashboard_id: number | null
     insight_short_id: string | null
     insight_name: string | null
     scope: string
@@ -37,6 +40,7 @@ export const createAnnotationTool: ToolConfig<
   description:
     'Create a new annotation in PostHog. Mark important events on your graphs with date and description.',
   version: '1.0.0',
+  errorExtractor: 'posthog-errors',
 
   params: {
     apiKey: {
@@ -58,6 +62,13 @@ export const createAnnotationTool: ToolConfig<
       description: 'PostHog cloud region: "us" or "eu" (default: "us")',
       default: 'us',
     },
+    host: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description:
+        'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+    },
     content: {
       type: 'string',
       required: true,
@@ -75,25 +86,28 @@ export const createAnnotationTool: ToolConfig<
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Scope of the annotation: "project" or "dashboard_item" (default: "project")',
+      description:
+        'Scope of the annotation: "project", "organization", "dashboard", or "dashboard_item" (default: "project")',
     },
     dashboard_item: {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'ID of dashboard item to attach this annotation to',
+      description:
+        'ID of the dashboard tile (insight) to attach this annotation to (used when scope is "dashboard_item")',
     },
-    insight_short_id: {
+    dashboard_id: {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Short ID of the insight to attach this annotation to',
+      description:
+        'ID of the dashboard to attach this annotation to (used when scope is "dashboard")',
     },
   },
 
   request: {
     url: (params) => {
-      const baseUrl = params.region === 'eu' ? 'https://eu.posthog.com' : 'https://us.posthog.com'
+      const baseUrl = getPostHogAppBaseUrl(params.region as 'us' | 'eu' | undefined, params.host)
       return `${baseUrl}/api/projects/${params.projectId}/annotations/`
     },
     method: 'POST',
@@ -115,8 +129,8 @@ export const createAnnotationTool: ToolConfig<
         body.dashboard_item = Number(params.dashboard_item)
       }
 
-      if (params.insight_short_id) {
-        body.insight_short_id = params.insight_short_id
+      if (params.dashboard_id) {
+        body.dashboard_id = Number(params.dashboard_id)
       }
 
       return body
@@ -136,6 +150,7 @@ export const createAnnotationTool: ToolConfig<
         updated_at: data.updated_at,
         created_by: data.created_by || null,
         dashboard_item: data.dashboard_item || null,
+        dashboard_id: data.dashboard_id || null,
         insight_short_id: data.insight_short_id || null,
         insight_name: data.insight_name || null,
         scope: data.scope || '',
@@ -175,6 +190,11 @@ export const createAnnotationTool: ToolConfig<
       description: 'ID of dashboard item this annotation is attached to',
       optional: true,
     },
+    dashboard_id: {
+      type: 'number',
+      description: 'ID of the dashboard this annotation is attached to',
+      optional: true,
+    },
     insight_short_id: {
       type: 'string',
       description: 'Short ID of the insight this annotation is attached to',
@@ -187,7 +207,7 @@ export const createAnnotationTool: ToolConfig<
     },
     scope: {
       type: 'string',
-      description: 'Scope of the annotation (project or dashboard_item)',
+      description: 'Scope of the annotation (project, organization, dashboard, or dashboard_item)',
     },
     deleted: {
       type: 'boolean',

apps/sim/tools/posthog/create_cohort.ts

@@ -1,9 +1,11 @@
+import { getPostHogAppBaseUrl } from '@/tools/posthog/utils'
 import type { ToolConfig } from '@/tools/types'
 
 interface PostHogCreateCohortParams {
   apiKey: string
   projectId: string
   region: string
+  host?: string
   name: string
   description?: string
   filters?: string
@@ -38,6 +40,7 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
     description:
       'Create a new cohort in PostHog. Requires cohort name and filter or query configuration.',
     version: '1.0.0',
+    errorExtractor: 'posthog-errors',
 
     params: {
       apiKey: {
@@ -59,6 +62,13 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
         description: 'PostHog cloud region: "us" or "eu" (default: "us")',
         default: 'us',
       },
+      host: {
+        type: 'string',
+        required: false,
+        visibility: 'user-only',
+        description:
+          'Self-hosted PostHog instance host (e.g., "posthog.mycompany.com"). Overrides the region setting when provided.',
+      },
       name: {
         type: 'string',
         required: false,
@@ -101,7 +111,7 @@ export const createCohortTool: ToolConfig<PostHogCreateCohortParams, PostHogCrea
 
     request: {
       url: (params) => {
-        const baseUrl = params.region === 'eu' ? 'https://eu.posthog.com' : 'https://us.posthog.com'
+        const baseUrl = getPostHogAppBaseUrl(params.region as 'us' | 'eu' | undefined, params.host)
         return `${baseUrl}/api/projects/${params.projectId}/cohorts/`
       },
       method: 'POST',