PostHog API — persons

naftiko: 1.0.0-alpha2
info:
  label: PostHog API — persons
  description: 'PostHog API — persons. 96 operations. Lead operation: persons. Self-contained Naftiko capability covering
    one Posthog business surface.'
  tags:
  - Posthog
  - persons
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    POSTHOG_API_KEY: POSTHOG_API_KEY
capability:
  consumes:
  - type: http
    namespace: posthog-persons
    baseUri: ''
    description: PostHog API — persons business capability. Self-contained, no shared references.
    resources:
    - name: api-environments-environment_id-persons
      path: /api/environments/{environment_id}/persons/
      operations:
      - name: environmentspersonslist
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: distinct_id
          in: query
          type: string
          description: Filter list by distinct id.
        - name: email
          in: query
          type: string
          description: Filter persons by email (exact match)
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: properties
          in: query
          type: array
          description: Filter Persons by person properties.
        - name: search
          in: query
          type: string
          description: Search persons, either by email (full text search) or distinct_id (exact match).
      - name: environmentspersonslist
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: distinct_id
          in: query
          type: string
          description: Filter list by distinct id.
        - name: email
          in: query
          type: string
          description: Filter persons by email (exact match)
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: properties
          in: query
          type: array
          description: Filter Persons by person properties.
        - name: search
          in: query
          type: string
          description: Search persons, either by email (full text search) or distinct_id (exact match).
    - name: api-environments-environment_id-persons-activity
      path: /api/environments/{environment_id}/persons/activity/
      operations:
      - name: environmentspersonsallactivityretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonsallactivityretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-persons-batch_by_distinct_ids
      path: /api/environments/{environment_id}/persons/batch_by_distinct_ids/
      operations:
      - name: environmentspersonsbatchbydistinctidscreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsbatchbydistinctidscreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-batch_by_uuids
      path: /api/environments/{environment_id}/persons/batch_by_uuids/
      operations:
      - name: environmentspersonsbatchbyuuidscreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsbatchbyuuidscreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-bulk_delete
      path: /api/environments/{environment_id}/persons/bulk_delete/
      operations:
      - name: environmentspersonsbulkdeletecreate
        method: POST
        description: This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs.
          You can pass in a maximum of 1000 IDs per call. Only events captured before the request will be deleted.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsbulkdeletecreate
        method: POST
        description: This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs.
          You can pass in a maximum of 1000 IDs per call. Only events captured before the request will be deleted.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-cohorts
      path: /api/environments/{environment_id}/persons/cohorts/
      operations:
      - name: environmentspersonscohortsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: person_id
          in: query
          type: string
          description: The person ID or UUID to get cohorts for.
          required: true
      - name: environmentspersonscohortsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: person_id
          in: query
          type: string
          description: The person ID or UUID to get cohorts for.
          required: true
    - name: api-environments-environment_id-persons-deletion_status
      path: /api/environments/{environment_id}/persons/deletion_status/
      operations:
      - name: environmentspersonsdeletionstatuslist
        method: GET
        description: List the status of queued event deletions for persons. When you delete a person with `delete_events=true`,
          an async deletion is queued. Use this endpoint to check whether those deletions are still pending or have been completed.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: person_uuid
          in: query
          type: string
          description: Filter by a specific person UUID.
        - name: status
          in: query
          type: string
          description: 'Filter by deletion status: ''pending'', ''completed'', or ''all''.'
      - name: environmentspersonsdeletionstatuslist
        method: GET
        description: List the status of queued event deletions for persons. When you delete a person with `delete_events=true`,
          an async deletion is queued. Use this endpoint to check whether those deletions are still pending or have been completed.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: person_uuid
          in: query
          type: string
          description: Filter by a specific person UUID.
        - name: status
          in: query
          type: string
          description: 'Filter by deletion status: ''pending'', ''completed'', or ''all''.'
    - name: api-environments-environment_id-persons-funnel
      path: /api/environments/{environment_id}/persons/funnel/
      operations:
      - name: environmentspersonsfunnelretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonsfunnelretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonsfunnelcreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsfunnelcreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-funnel-correlation
      path: /api/environments/{environment_id}/persons/funnel/correlation/
      operations:
      - name: environmentspersonsfunnelcorrelationretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonsfunnelcorrelationretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonsfunnelcorrelationcreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsfunnelcorrelationcreate
        method: POST
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-lifecycle
      path: /api/environments/{environment_id}/persons/lifecycle/
      operations:
      - name: environmentspersonslifecycleretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonslifecycleretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-persons-properties_at_time
      path: /api/environments/{environment_id}/persons/properties_at_time/
      operations:
      - name: environmentspersonspropertiesattimeretrieve
        method: GET
        description: Get person properties as they existed at a specific point in time.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: debug
          in: query
          type: boolean
          description: 'Whether to include debug information with raw events (only works when DEBUG=True, default: false)'
        - name: distinct_id
          in: query
          type: string
          description: The distinct_id of the person (mutually exclusive with person_id)
        - name: format
          in: query
          type: string
        - name: include_set_once
          in: query
          type: boolean
          description: 'Whether to handle $set_once operations (default: false)'
        - name: person_id
          in: query
          type: string
          description: The person_id (UUID) to build properties for (mutually exclusive with distinct_id)
        - name: timestamp
          in: query
          type: string
          description: ISO datetime string for the point in time (e.g., '2023-06-15T14:30:00Z')
          required: true
      - name: environmentspersonspropertiesattimeretrieve
        method: GET
        description: Get person properties as they existed at a specific point in time.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: debug
          in: query
          type: boolean
          description: 'Whether to include debug information with raw events (only works when DEBUG=True, default: false)'
        - name: distinct_id
          in: query
          type: string
          description: The distinct_id of the person (mutually exclusive with person_id)
        - name: format
          in: query
          type: string
        - name: include_set_once
          in: query
          type: boolean
          description: 'Whether to handle $set_once operations (default: false)'
        - name: person_id
          in: query
          type: string
          description: The person_id (UUID) to build properties for (mutually exclusive with distinct_id)
        - name: timestamp
          in: query
          type: string
          description: ISO datetime string for the point in time (e.g., '2023-06-15T14:30:00Z')
          required: true
    - name: api-environments-environment_id-persons-reset_person_distinct_id
      path: /api/environments/{environment_id}/persons/reset_person_distinct_id/
      operations:
      - name: environmentspersonsresetpersondistinctidcreate
        method: POST
        description: Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsresetpersondistinctidcreate
        method: POST
        description: Reset a distinct_id for a deleted person. This allows the distinct_id to be used again.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-trends
      path: /api/environments/{environment_id}/persons/trends/
      operations:
      - name: environmentspersonstrendsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
      - name: environmentspersonstrendsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-persons-values
      path: /api/environments/{environment_id}/persons/values/
      operations:
      - name: environmentspersonsvaluesretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: key
          in: query
          type: string
          description: The person property key to get values for (e.g., 'email', 'plan', 'role').
          required: true
        - name: value
          in: query
          type: string
          description: Optional search string to filter values (case-insensitive substring match).
      - name: environmentspersonsvaluesretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: key
          in: query
          type: string
          description: The person property key to get values for (e.g., 'email', 'plan', 'role').
          required: true
        - name: value
          in: query
          type: string
          description: Optional search string to filter values (case-insensitive substring match).
    - name: api-environments-environment_id-persons-id
      path: /api/environments/{environment_id}/persons/{id}/
      operations:
      - name: environmentspersonsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
      - name: environmentspersonsretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
      - name: environmentspersonsupdate
        method: PUT
        description: Only for setting properties on the person. "properties" from the request data will be updated via a "$set"
          event.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonsupdate
        method: PUT
        description: Only for setting properties on the person. "properties" from the request data will be updated via a "$set"
          event.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonspartialupdate
        method: PATCH
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentspersonspartialupdate
        method: PATCH
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: A unique value identifying this person. Accepts both numeric ID and UUID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-persons-id-activity
      path: /api/environments/{environment_id}/persons/{id}/activity/
      operations:
      - name: environmentspersonsactivityretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this person.
          required: true
      - name: environmentspersonsactivityretrieve
        method: GET
        description: This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using
          the [capture API](https://posthog.com/docs/api/capture), the `$set

# --- truncated at 32 KB (192 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posthog/refs/heads/main/capabilities/posthog-persons.yaml