{"openapi":"3.1.0","info":{"title":"PostHog (BYOK) API","version":"0.1.0","description":"PostHog (BYOK) lets an AI assistant read your own PostHog data through the PostHog API with a key you supply (personal API key (with read scopes)). Read-only: 8 tools (get_current_user, list_organizations, list_projects, list_insights, list_dashboards, list_feature_flags, list_persons, list_events). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-posthog.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-posthog/docs"},"termsOfService":"https://connectorbay.com/byok-posthog/terms"},"servers":[{"url":"https://byok-posthog.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-posthog/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_current_user":{"post":{"operationId":"get_current_user","summary":"Show the PostHog user the key belongs to: name, email, join date and the current organization and project. Use for \"Whic","description":"Show the PostHog user the key belongs to: name, email, join date and the current organization and project. Use for \"Which PostHog user and project is my API key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"}},"required":["region"],"title":"get_current_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_organizations":{"post":{"operationId":"list_organizations","summary":"List the PostHog organizations you belong to, with your membership level and member count. Use for \"Which PostHog organi","description":"List the PostHog organizations you belong to, with your membership level and member count. Use for \"Which PostHog organizations am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region"],"title":"list_organizationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List the projects of one PostHog organization, with id, name, time zone and whether events have arrived. Use for \"What p","description":"List the projects of one PostHog organization, with id, name, time zone and whether events have arrived. Use for \"What projects does my PostHog organization have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"organization_id":{"description":"Organization id (a UUID, see list_organizations).","maxLength":200,"title":"Organization Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name matches this text.","title":"Search"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region","organization_id"],"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_insights":{"post":{"operationId":"list_insights","summary":"List saved insights (trends, funnels, retention and other analyses) of a project with name, tags and last change; comput","description":"List saved insights (trends, funnels, retention and other analyses) of a project with name, tags and last change; computed results are left out. Use for \"What saved insights do I have in my PostHog project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"project_id":{"description":"PostHog project id (a number, see list_projects or get_current_user).","maxLength":200,"title":"Project Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only insights whose name or description matches this text.","title":"Search"},"favorited":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only favorited insights.","title":"Favorited"},"saved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only saved insights.","title":"Saved"},"basic":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to skip the computed results of each insight and return metadata only.","title":"Basic"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region","project_id"],"title":"list_insightsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_dashboards":{"post":{"operationId":"list_dashboards","summary":"List the dashboards of a project with name, description, pinned and shared flags and last access time. Use for \"Which da","description":"List the dashboards of a project with name, description, pinned and shared flags and last access time. Use for \"Which dashboards exist in my PostHog project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"project_id":{"description":"PostHog project id (a number, see list_projects or get_current_user).","maxLength":200,"title":"Project Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only dashboards whose name matches this text.","title":"Search"},"pinned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only pinned dashboards.","title":"Pinned"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region","project_id"],"title":"list_dashboardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_feature_flags":{"post":{"operationId":"list_feature_flags","summary":"List the feature flags of a project with key, name, active state, status, tags and when each was last called. Use for \"W","description":"List the feature flags of a project with key, name, active state, status, tags and when each was last called. Use for \"Which feature flags are active in my PostHog project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"project_id":{"description":"PostHog project id (a number, see list_projects or get_current_user).","maxLength":200,"title":"Project Id","type":"string"},"active":{"anyOf":[{"enum":["true","false","STALE"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by state: true, false or STALE.","title":"Active"},"type":{"anyOf":[{"enum":["boolean","experiment","multivariant","remote_config"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by flag type: boolean, experiment, multivariant or remote_config.","title":"Type"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only flags whose key or name matches this text.","title":"Search"},"key":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the flag with exactly this key.","title":"Key"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region","project_id"],"title":"list_feature_flagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_persons":{"post":{"operationId":"list_persons","summary":"List the persons (tracked users) of a project with id, distinct ids, creation and last seen time; can search by text, em","description":"List the persons (tracked users) of a project with id, distinct ids, creation and last seen time; can search by text, email or distinct id. Use for \"Find the PostHog person with email jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"project_id":{"description":"PostHog project id (a number, see list_projects or get_current_user).","maxLength":200,"title":"Project Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to look for in the person's email, name or distinct id.","title":"Search"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the person with this email property.","title":"Email"},"distinct_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the person with this distinct id.","title":"Distinct Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Offset"}},"required":["region","project_id"],"title":"list_personsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_events":{"post":{"operationId":"list_events","summary":"List recent raw events of a project (legacy endpoint; only the last 24 hours unless after is given) with event name, per","description":"List recent raw events of a project (legacy endpoint; only the last 24 hours unless after is given) with event name, person and time. Use for \"What events happened in my PostHog project in the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"PostHog Cloud region of your account: us (us.posthog.com) or eu (eu.posthog.com).","enum":["us","eu"],"title":"Region","type":"string"},"project_id":{"description":"PostHog project id (a number, see list_projects or get_current_user).","maxLength":200,"title":"Project Id","type":"string"},"event":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events with this exact name, for example '$pageview'.","title":"Event"},"after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events after this ISO 8601 time, for example 2026-10-01T00:00:00Z (the range to before must be under one year).","title":"After"},"before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events before this ISO 8601 time.","title":"Before"},"person_id":{"anyOf":[{"maximum":2147483647,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only events of the person with this numeric id.","title":"Person Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many events to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":50000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many events to skip (the API refuses offsets above 50000).","title":"Offset"}},"required":["region","project_id"],"title":"list_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}