User

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
PATCH
DELETE
POST

List all user interviews

Also available via the PostHog MCP server:

  • user-interviews-list — List user interview responses

Required API key scopes

user_interview:read

Query parameters

  • classifications
    string
  • limit
    integer
  • offset
    integer
  • topic
    string

Response


Example request

GET /api/projects/:project_id/user_interviews
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "interviewee_emails": [
        "string"
      ],
      "interviewee_identifier": "string",
      "topic": "27754427-e2b6-4edb-9132-e6e120f5cc9a",
      "transcript": "string",
      "summary": "string",
      "classifications": [
        "abandoned"
      ],
      "audio": "http://example.com"
    }
  ]
}

Create user interviews

Required API key scopes

user_interview:write

Request parameters

  • interviewee_emails
    array
  • summary
    string
  • classifications
    Click to open
    array
  • audio
    string

Response


Example request

POST /api/projects/:project_id/user_interviews
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/\
	-d audio="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "interviewee_emails": [
    "string"
  ],
  "interviewee_identifier": "string",
  "topic": "27754427-e2b6-4edb-9132-e6e120f5cc9a",
  "transcript": "string",
  "summary": "string",
  "classifications": [
    "abandoned"
  ],
  "audio": "http://example.com"
}

Retrieve user interviews

Also available via the PostHog MCP server:

  • user-interviews-retrieve — Retrieve a user interview response

Required API key scopes

user_interview:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/user_interviews/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "interviewee_emails": [
    "string"
  ],
  "interviewee_identifier": "string",
  "topic": "27754427-e2b6-4edb-9132-e6e120f5cc9a",
  "transcript": "string",
  "summary": "string",
  "classifications": [
    "abandoned"
  ],
  "audio": "http://example.com"
}

Update user interviews

Required API key scopes

user_interview:write

Path parameters

  • id
    string

Request parameters

  • interviewee_emails
    array
  • summary
    string
  • classifications
    Click to open
    array
  • audio
    string

Response


Example request

PATCH /api/projects/:project_id/user_interviews/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/:id/\
	-d created_by=undefined

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "interviewee_emails": [
    "string"
  ],
  "interviewee_identifier": "string",
  "topic": "27754427-e2b6-4edb-9132-e6e120f5cc9a",
  "transcript": "string",
  "summary": "string",
  "classifications": [
    "abandoned"
  ],
  "audio": "http://example.com"
}

Delete user interviews

Required API key scopes

user_interview:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/user_interviews/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/:id/

Example response

Status 204 No response body

Create user interviews search

Embed query with the same model used to index interview transcripts and summaries, then return the top matches by cosine distance. Each match is a single (interview, document_type) pair — an interview can appear up to twice if both its transcript and summary score above other interviews. Useful for surfacing relevant interview snippets in natural language, without exact keyword matches.

Required API key scopes

user_interview:read

Request parameters

  • query
    string
  • document_types
    Click to open
    array
  • topic_id
    stringnull
  • classifications
    Click to open
    array
  • limit
    integer

Example request

POST /api/projects/:project_id/user_interviews/search
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/user_interviews/search/\
	-d query="string"

Example response

Status 200 Matches ranked by cosine similarity (descending).
RESPONSE
{
  "interview_id": "c7f9da44-f841-4f3a-8fcf-5eabcb3fb324",
  "document_type": "transcript",
  "similarity": 0.1,
  "content_snippet": "string",
  "interviewee_identifier": "string",
  "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  "created_at": "2019-08-24T14:15:22Z"
}