PostHog API — events

naftiko: 1.0.0-alpha2
info:
  label: PostHog API — events
  description: 'PostHog API — events. 6 operations. Lead operation: events. Self-contained Naftiko capability covering one
    Posthog business surface.'
  tags:
  - Posthog
  - events
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    POSTHOG_API_KEY: POSTHOG_API_KEY
capability:
  consumes:
  - type: http
    namespace: posthog-events
    baseUri: ''
    description: PostHog API — events business capability. Self-contained, no shared references.
    resources:
    - name: api-environments-environment_id-events
      path: /api/environments/{environment_id}/events/
      operations:
      - name: environmentseventslist
        method: GET
        description: This endpoint allows you to list and filter events.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: string
          description: 'Only return events with a timestamp after this time. Default: now() - 24 hours.'
        - name: before
          in: query
          type: string
          description: 'Only return events with a timestamp before this time. Default: now() + 5 seconds.'
        - name: distinct_id
          in: query
          type: integer
          description: Filter list by distinct id.
        - name: event
          in: query
          type: string
          description: Filter list by event. For example `user sign up` or `$pageview`.
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: The maximum number of results to return
        - name: offset
          in: query
          type: integer
          description: 'Allows to skip first offset rows. Will fail for value larger than 100000. Read about proper way of
            paginating: https://posthog.com/docs/api/queries#5-use-timest'
        - name: person_id
          in: query
          type: integer
          description: Filter list by person id.
        - name: properties
          in: query
          type: array
          description: Filter events by event property, person property, cohort, groups and more.
        - name: select
          in: query
          type: array
          description: (Experimental) JSON-serialized array of HogQL expressions to return
        - name: where
          in: query
          type: array
          description: (Experimental) JSON-serialized array of HogQL expressions that must pass
    - name: api-environments-environment_id-events-values
      path: /api/environments/{environment_id}/events/values/
      operations:
      - name: environmentseventsvaluesretrieve
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-events-id
      path: /api/environments/{environment_id}/events/{id}/
      operations:
      - name: environmentseventsretrieve
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          required: true
    - name: api-projects-project_id-events
      path: /api/projects/{project_id}/events/
      operations:
      - name: eventslist
        method: GET
        description: This endpoint allows you to list and filter events.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: string
          description: 'Only return events with a timestamp after this time. Default: now() - 24 hours.'
        - name: before
          in: query
          type: string
          description: 'Only return events with a timestamp before this time. Default: now() + 5 seconds.'
        - name: distinct_id
          in: query
          type: integer
          description: Filter list by distinct id.
        - name: event
          in: query
          type: string
          description: Filter list by event. For example `user sign up` or `$pageview`.
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: The maximum number of results to return
        - name: offset
          in: query
          type: integer
          description: 'Allows to skip first offset rows. Will fail for value larger than 100000. Read about proper way of
            paginating: https://posthog.com/docs/api/queries#5-use-timest'
        - name: person_id
          in: query
          type: integer
          description: Filter list by person id.
        - name: properties
          in: query
          type: array
          description: Filter events by event property, person property, cohort, groups and more.
        - name: select
          in: query
          type: array
          description: (Experimental) JSON-serialized array of HogQL expressions to return
        - name: where
          in: query
          type: array
          description: (Experimental) JSON-serialized array of HogQL expressions that must pass
    - name: api-projects-project_id-events-values
      path: /api/projects/{project_id}/events/values/
      operations:
      - name: eventsvaluesretrieve
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-projects-project_id-events-id
      path: /api/projects/{project_id}/events/{id}/
      operations:
      - name: eventsretrieve
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          required: true
    authentication:
      type: bearer
      token: '{{env.POSTHOG_API_KEY}}'
  exposes:
  - type: rest
    namespace: posthog-events-rest
    port: 8080
    description: REST adapter for PostHog API — events. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/api/environments/{environment-id}/events
      name: api-environments-environment-id-events
      description: REST surface for api-environments-environment_id-events.
      operations:
      - method: GET
        name: environmentseventslist
        description: This endpoint allows you to list and filter events.
        call: posthog-events.environmentseventslist
        with:
          after: rest.after
          before: rest.before
          distinct_id: rest.distinct_id
          event: rest.event
          format: rest.format
          limit: rest.limit
          offset: rest.offset
          person_id: rest.person_id
          properties: rest.properties
          select: rest.select
          where: rest.where
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/environments/{environment-id}/events/values
      name: api-environments-environment-id-events-values
      description: REST surface for api-environments-environment_id-events-values.
      operations:
      - method: GET
        name: environmentseventsvaluesretrieve
        description: environmentseventsvaluesretrieve
        call: posthog-events.environmentseventsvaluesretrieve
        with:
          format: rest.format
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/environments/{environment-id}/events/{id}
      name: api-environments-environment-id-events-id
      description: REST surface for api-environments-environment_id-events-id.
      operations:
      - method: GET
        name: environmentseventsretrieve
        description: environmentseventsretrieve
        call: posthog-events.environmentseventsretrieve
        with:
          format: rest.format
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/events
      name: api-projects-project-id-events
      description: REST surface for api-projects-project_id-events.
      operations:
      - method: GET
        name: eventslist
        description: This endpoint allows you to list and filter events.
        call: posthog-events.eventslist
        with:
          after: rest.after
          before: rest.before
          distinct_id: rest.distinct_id
          event: rest.event
          format: rest.format
          limit: rest.limit
          offset: rest.offset
          person_id: rest.person_id
          properties: rest.properties
          select: rest.select
          where: rest.where
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/events/values
      name: api-projects-project-id-events-values
      description: REST surface for api-projects-project_id-events-values.
      operations:
      - method: GET
        name: eventsvaluesretrieve
        description: eventsvaluesretrieve
        call: posthog-events.eventsvaluesretrieve
        with:
          format: rest.format
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/events/{id}
      name: api-projects-project-id-events-id
      description: REST surface for api-projects-project_id-events-id.
      operations:
      - method: GET
        name: eventsretrieve
        description: eventsretrieve
        call: posthog-events.eventsretrieve
        with:
          format: rest.format
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: posthog-events-mcp
    port: 9090
    transport: http
    description: MCP adapter for PostHog API — events. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: this-endpoint-allows-you-list
      description: This endpoint allows you to list and filter events.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.environmentseventslist
      with:
        after: tools.after
        before: tools.before
        distinct_id: tools.distinct_id
        event: tools.event
        format: tools.format
        limit: tools.limit
        offset: tools.offset
        person_id: tools.person_id
        properties: tools.properties
        select: tools.select
        where: tools.where
      outputParameters:
      - type: object
        mapping: $.
    - name: environmentseventsvaluesretrieve
      description: environmentseventsvaluesretrieve
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.environmentseventsvaluesretrieve
      with:
        format: tools.format
      outputParameters:
      - type: object
        mapping: $.
    - name: environmentseventsretrieve
      description: environmentseventsretrieve
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.environmentseventsretrieve
      with:
        format: tools.format
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: this-endpoint-allows-you-list-2
      description: This endpoint allows you to list and filter events.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.eventslist
      with:
        after: tools.after
        before: tools.before
        distinct_id: tools.distinct_id
        event: tools.event
        format: tools.format
        limit: tools.limit
        offset: tools.offset
        person_id: tools.person_id
        properties: tools.properties
        select: tools.select
        where: tools.where
      outputParameters:
      - type: object
        mapping: $.
    - name: eventsvaluesretrieve
      description: eventsvaluesretrieve
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.eventsvaluesretrieve
      with:
        format: tools.format
      outputParameters:
      - type: object
        mapping: $.
    - name: eventsretrieve
      description: eventsretrieve
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: posthog-events.eventsretrieve
      with:
        format: tools.format
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.