Conversations

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

Endpoints

`GET`
`POST`
`GET`
`DELETE`
`POST`
`PATCH`
`POST`
`GET`
`POST`
`PATCH`
`DELETE`
`POST`
`GET`
`GET`
`GET`
`GET`
`PATCH`
`DELETE`
`POST`

Required API key scopes

conversation:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/conversations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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",
      "status": "idle",
      "title": "string",
      "topic": "web_analytics",
      "user": {
        "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",
      "updated_at": "2019-08-24T14:15:22Z",
      "type": "assistant",
      "is_internal": true,
      "slack_thread_key": "string",
      "slack_workspace_domain": "string",
      "task": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "task_number": 0,
        "slug": "string",
        "title": "string",
        "title_manually_set": true,
        "description": "string",
        "origin_product": "string",
        "runtime": "acp",
        "repository": "string",
        "github_integration": 0,
        "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
        "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
        "json_schema": {},
        "internal": true,
        "archived": true,
        "archived_at": "2019-08-24T14:15:22Z",
        "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "created_by": {
          "id": 0,
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "distinct_id": "string",
          "first_name": "string",
          "last_name": "string",
          "email": "string",
          "is_email_verified": true,
          "hedgehog_config": {},
          "role_at_organization": "string"
        },
        "ci_prompt": "string"
      }
    }
  ]
}

Create conversations

Unified endpoint that handles both conversation creation and streaming.

If message is provided: Start new conversation processing
If no message: Stream from existing conversation

Required API key scopes

conversation:write

Request parameters

content
string | null
conversation
string
contextual_tools
object
ui_context
billing_context
trace_id
string
session_id
string
agent_mode
is_sandbox
boolean
Default: false
resume_payload

Response

Example request

POST /api/projects/:project_id/conversations
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/conversations/\
	-d content="string",\
	-d conversation="string",\
	-d trace_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string",
		"conversation": "string",
		"trace_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "content": "string",
  "conversation": "a2d9c3ee-03b3-403a-b1c2-42b286bec1aa",
  "contextual_tools": {},
  "ui_context": null,
  "billing_context": null,
  "trace_id": "df570c03-5a03-4cea-8df0-c162d05127ac",
  "session_id": "string",
  "agent_mode": "product_analytics",
  "is_sandbox": false,
  "resume_payload": null
}

Retrieve conversations

Required API key scopes

conversation:read

Path parameters

conversation
string

Response

Example request

GET /api/projects/:project_id/conversations/:conversation
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/:conversation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "idle",
  "title": "string",
  "topic": "web_analytics",
  "user": {
    "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",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "assistant",
  "is_internal": true,
  "slack_thread_key": "string",
  "slack_workspace_domain": "string",
  "messages": [
    {}
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "agent_runtime": "langgraph",
  "is_sandbox": true,
  "pending_approvals": [
    {}
  ],
  "task": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_number": 0,
    "slug": "string",
    "title": "string",
    "title_manually_set": true,
    "description": "string",
    "origin_product": "string",
    "runtime": "acp",
    "repository": "string",
    "github_integration": 0,
    "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
    "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
    "json_schema": {},
    "internal": true,
    "archived": true,
    "archived_at": "2019-08-24T14:15:22Z",
    "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    },
    "ci_prompt": "string"
  }
}

Delete conversations

Delete a conversation.

Required API key scopes

conversation:write

Path parameters

conversation
string

Example request

DELETE /api/projects/:project_id/conversations/:conversation
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/conversations/:conversation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create conversations append message

Appends a message to an existing conversation without triggering AI processing. This is used for client-side generated messages that need to be persisted (e.g., support ticket confirmation messages).

Path parameters

conversation
string

Request parameters

content
string

Response

Example request

POST /api/projects/:project_id/conversations/:conversation/append_message
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/conversations/:conversation/append_message/\
	-d content="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/append_message/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "content": "string"
}

Update conversations cancel

Cancel the conversation's in-progress LangGraph run.

Path parameters

conversation
string

Request parameters

Example request

PATCH /api/projects/:project_id/conversations/:conversation/cancel
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/conversations/:conversation/cancel/\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/cancel/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 204 Cancellation accepted, or already cancelling.

Status 422 Failed to cancel the conversation.

Create conversations open

Create-or-resume a sandbox conversation — the single sandbox session opener. With content, processes the turn (first message, in-progress follow-up, or terminal resume); without content, warms a sandbox that idles awaiting the first message. Returns the (task, run) handle the frontend opens SSE against. The conversation row is created on first use from the URL id.

Path parameters

conversation
string

Request parameters

content
string | null
trace_id
string
attached_context
array
initial_permission_mode
task_id
string

Response

Example request

POST /api/projects/:project_id/conversations/:conversation/open
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/conversations/:conversation/open/\
	-d content="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/open/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "task_id": "string",
  "run_id": "string",
  "trace_id": "string",
  "run_status": "string",
  "just_created_run": true
}

Status 204 Warm request that provisioned nothing (pool full / released).

Status 400 Conversation or task uses an unsupported runtime.

Retrieve conversations queue

Path parameters

conversation
string

Response

Example request

GET /api/projects/:project_id/conversations/:conversation/queue
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/:conversation/queue/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/queue/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "idle",
  "title": "string",
  "topic": "web_analytics",
  "user": {
    "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",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "assistant",
  "is_internal": true,
  "slack_thread_key": "string",
  "slack_workspace_domain": "string",
  "messages": [
    {}
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "agent_runtime": "langgraph",
  "is_sandbox": true,
  "pending_approvals": [
    {}
  ],
  "task": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_number": 0,
    "slug": "string",
    "title": "string",
    "title_manually_set": true,
    "description": "string",
    "origin_product": "string",
    "runtime": "acp",
    "repository": "string",
    "github_integration": 0,
    "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
    "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
    "json_schema": {},
    "internal": true,
    "archived": true,
    "archived_at": "2019-08-24T14:15:22Z",
    "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    },
    "ci_prompt": "string"
  }
}

Create conversations queue

Path parameters

conversation
string

Request parameters

Response

Example request

POST /api/projects/:project_id/conversations/:conversation/queue
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/conversations/:conversation/queue/\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/queue/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "idle",
  "title": "string",
  "topic": "web_analytics",
  "user": {
    "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",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "assistant",
  "is_internal": true,
  "slack_thread_key": "string",
  "slack_workspace_domain": "string",
  "messages": [
    {}
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "agent_runtime": "langgraph",
  "is_sandbox": true,
  "pending_approvals": [
    {}
  ],
  "task": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_number": 0,
    "slug": "string",
    "title": "string",
    "title_manually_set": true,
    "description": "string",
    "origin_product": "string",
    "runtime": "acp",
    "repository": "string",
    "github_integration": 0,
    "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
    "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
    "json_schema": {},
    "internal": true,
    "archived": true,
    "archived_at": "2019-08-24T14:15:22Z",
    "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    },
    "ci_prompt": "string"
  }
}

Update conversations queue

Path parameters

conversation
string
queue_id
string

Request parameters

Response

Example request

PATCH /api/projects/:project_id/conversations/:conversation/queue/:queue_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/conversations/:conversation/queue/:queue_id/\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/queue/{queue_id}/".format(
        project_id=project_id,
		conversation="<the conversation>",,
		queue_id="<the queue id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "idle",
  "title": "string",
  "topic": "web_analytics",
  "user": {
    "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",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "assistant",
  "is_internal": true,
  "slack_thread_key": "string",
  "slack_workspace_domain": "string",
  "messages": [
    {}
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "agent_runtime": "langgraph",
  "is_sandbox": true,
  "pending_approvals": [
    {}
  ],
  "task": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_number": 0,
    "slug": "string",
    "title": "string",
    "title_manually_set": true,
    "description": "string",
    "origin_product": "string",
    "runtime": "acp",
    "repository": "string",
    "github_integration": 0,
    "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
    "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
    "json_schema": {},
    "internal": true,
    "archived": true,
    "archived_at": "2019-08-24T14:15:22Z",
    "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    },
    "ci_prompt": "string"
  }
}

Delete conversations queue

Path parameters

conversation
string
queue_id
string

Example request

DELETE /api/projects/:project_id/conversations/:conversation/queue/:queue_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/conversations/:conversation/queue/:queue_id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/queue/{queue_id}/".format(
        project_id=project_id,
		conversation="<the conversation>",,
		queue_id="<the queue id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create conversations queue clear

Path parameters

conversation
string

Request parameters

Response

Example request

POST /api/projects/:project_id/conversations/:conversation/queue/clear
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/conversations/:conversation/queue/clear/\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/{conversation}/queue/clear/".format(
        project_id=project_id,
		conversation="<the conversation>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "idle",
  "title": "string",
  "topic": "web_analytics",
  "user": {
    "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",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "assistant",
  "is_internal": true,
  "slack_thread_key": "string",
  "slack_workspace_domain": "string",
  "messages": [
    {}
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "agent_runtime": "langgraph",
  "is_sandbox": true,
  "pending_approvals": [
    {}
  ],
  "task": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_number": 0,
    "slug": "string",
    "title": "string",
    "title_manually_set": true,
    "description": "string",
    "origin_product": "string",
    "runtime": "acp",
    "repository": "string",
    "github_integration": 0,
    "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
    "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
    "json_schema": {},
    "internal": true,
    "archived": true,
    "archived_at": "2019-08-24T14:15:22Z",
    "latest_run": "9c6e887d-05e4-4850-8ede-1a273a702178",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    },
    "ci_prompt": "string"
  }
}

List all conversations ai context account properties

Account-target Customer analytics properties that can be included in AI reply context. Capped at the first 500 properties by name.

Required API key scopes

account:read

Example request

GET /api/projects/:project_id/conversations/ai_context_account_properties
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/ai_context_account_properties/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/ai_context_account_properties/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string"
}

Retrieve conversations ai reply playbook

Inherited support-reply playbook for this project, plus the team's custom addendum if any.

Required API key scopes

project:read

Response

Example request

GET /api/projects/:project_id/conversations/ai_reply_playbook
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/ai_reply_playbook/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/ai_reply_playbook/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "inherited_instructions": "string",
  "custom_instructions": "string",
  "is_customized": true,
  "default_version": 0,
  "posthog_overlay_version": 0,
  "docs_source": "string",
  "max_chars": 0
}

List all conversations tickets

Also available via the PostHog MCP server:
conversations-tickets-list — List support tickets

List tickets with person data attached.

Required API key scopes

ticket:read

Query parameters

ai_triage_result
string
assignee
string
channel_detail
string
One of: "github_issue""slack_bot_mention""slack_channel_message""slack_emoji_reaction""teams_bot_mention""teams_channel_message""widget_api""widget_embedded"
channel_source
string
One of: "email""github""slack""teams""widget"
date_from
string
date_to
string
distinct_ids
string
emails
string
limit
integer
offset
integer
order_by
string
One of: "-created_at""-sla_due_at""-ticket_number""-updated_at""created_at""sla_due_at""ticket_number""updated_at"
priority
string
search
string
sla
string
One of: "at-risk""breached""on-track"
snoozed
boolean
status
string
tags
string
tags_all
string
tags_exclude
string
view
string

Response

Example request

GET /api/projects/:project_id/conversations/tickets
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/conversations/tickets/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/tickets/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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",
      "ticket_number": 0,
      "channel_source": "widget",
      "channel_detail": "slack_channel_message",
      "distinct_id": "string",
      "status": "new",
      "priority": "low",
      "assignee": {
        "id": "string",
        "type": "string",
        "user": {
          "property1": "string",
          "property2": "string"
        },
        "role": {
          "property1": "string",
          "property2": "string"
        }
      },
      "anonymous_traits": null,
      "identity_verified": true,
      "ai_resolved": true,
      "escalation_reason": "string",
      "ai_triage": null,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "message_count": 0,
      "last_message_at": "2019-08-24T14:15:22Z",
      "last_message_text": "string",
      "unread_team_count": 0,
      "unread_customer_count": 0,
      "session_id": "string",
      "session_context": {
        "current_url": "string",
        "replay_url": "string"
      },
      "sla_due_at": "2019-08-24T14:15:22Z",
      "snoozed_until": "2019-08-24T14:15:22Z",
      "slack_channel_id": "string",
      "slack_thread_ts": "string",
      "slack_team_id": "string",
      "email_subject": "string",
      "email_from": "user@example.com",
      "email_to": "string",
      "cc_participants": null,
      "github_repo": "string",
      "github_issue_number": 0,
      "zendesk_ticket_id": 0,
      "organization_id": "string",
      "organization_id_source": "string",
      "person": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "distinct_ids": [
          "string"
        ],
        "properties": {},
        "created_at": "2019-08-24T14:15:22Z",
        "is_identified": true
      },
      "tags": [
        null
      ],
      "user_access_level": "string"
    }
  ]
}

Retrieve conversations tickets

Also available via the PostHog MCP server:
conversations-tickets-retrieve — Get support ticket

Get single ticket and mark as read by team.

Required API key scopes

ticket:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/conversations/tickets/: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/conversations/tickets/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/conversations/tickets/{conversation_id}/".format(
        project_id=project_id,
		conversation_id="<the conversation id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "ticket_number": 0,
  "channel_source": "widget",
  "channel_detail": "slack_channel_message",
  "distinct_id": "string",
  "status": "new",
  "priority": "low",
  "assignee": {
    "id": "string",
    "type": "string",
    "user": {
      "property1": "string",
      "property2": "string"
    },
    "role": {
      "property1": "string",
      "property2": "string"
    }
  },
  "anonymous_traits": null,
  "identity_verified": true,
  "ai_resolved": true,
  "escalation_reason": "string",
  "ai_triage": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "message_count": 0,
  "last_message_at": "2019-08-24T14:15:22Z",
  "last_message_text": "string",
  "unread_team_count": 0,
  "unread_customer_count": 0,
  "session_id": "string",
  "session_context": {
    "current_url": "string",
    "replay_url": "string"
  },
  "sla_due_at": "2019-08-24T14:15:22Z",
  "snoozed_until": "2019-08-24T14:15:22Z",
  "slack_channel_id": "string",
  "slack_thread_ts": "string",
  "slack_team_id": "string",
  "email_subject": "string",
  "email_from": "user@example.com",
  "email_to": "string",
  "cc_participants": null,
  "github_repo": "string",
  "github_issue_number": 0,
  "zendesk_ticket_id": 0,
  "organization_id": "string",
  "organization_id_source": "string",
  "person": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "distinct_ids": [
      "string"
    ],
    "properties": {},
    "created_at": "2019-08-24T14:15:22Z",
    "is_identified": true
  },
  "tags": [
    null
  ],
  "user_access_level": "string"
}

Update conversations tickets

Required API key scopes

ticket:write

Path parameters

id
string

Request parameters

status
priority
assignee
anonymous_traits
ai_resolved
boolean
escalation_reason
string | null
sla_due_at
string | null
snoozed_until
string | null
tags
array

Response

Example request

PATCH /api/projects/:project_id/conversations/tickets/: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/conversations/tickets/:id/\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/conversations/tickets/{conversation_id}/".format(
        project_id=project_id,
		conversation_id="<the conversation id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "ticket_number": 0,
  "channel_source": "widget",
  "channel_detail": "slack_channel_message",
  "distinct_id": "string",
  "status": "new",
  "priority": "low",
  "assignee": {
    "id": "string",
    "type": "string",
    "user": {
      "property1": "string",
      "property2": "string"
    },
    "role": {
      "property1": "string",
      "property2": "string"
    }
  },
  "anonymous_traits": null,
  "identity_verified": true,
  "ai_resolved": true,
  "escalation_reason": "string",
  "ai_triage": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "message_count": 0,
  "last_message_at": "2019-08-24T14:15:22Z",
  "last_message_text": "string",
  "unread_team_count": 0,
  "unread_customer_count": 0,
  "session_id": "string",
  "session_context": {
    "current_url": "string",
    "replay_url": "string"
  },
  "sla_due_at": "2019-08-24T14:15:22Z",
  "snoozed_until": "2019-08-24T14:15:22Z",
  "slack_channel_id": "string",
  "slack_thread_ts": "string",
  "slack_team_id": "string",
  "email_subject": "string",
  "email_from": "user@example.com",
  "email_to": "string",
  "cc_participants": null,
  "github_repo": "string",
  "github_issue_number": 0,
  "zendesk_ticket_id": 0,
  "organization_id": "string",
  "organization_id_source": "string",
  "person": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "distinct_ids": [
      "string"
    ],
    "properties": {},
    "created_at": "2019-08-24T14:15:22Z",
    "is_identified": true
  },
  "tags": [
    null
  ],
  "user_access_level": "string"
}

Delete conversations tickets

Soft-delete a ticket. A daily sweeper hard-deletes it after the grace window.

Required API key scopes

ticket:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/conversations/tickets/: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/conversations/tickets/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/conversations/tickets/{conversation_id}/".format(
        project_id=project_id,
		conversation_id="<the conversation id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create conversations tickets ai feedback

Record reviewer feedback on an AI reply, captured to the internal analytics project.

Required API key scopes

ticket:write

Path parameters

id
string

Request parameters

message_id
string
rating
feedback_text
string

Example request

POST /api/projects/:project_id/conversations/tickets/:id/ai_feedback
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/conversations/tickets/:id/ai_feedback/\
	-d message_id="string",\
	-d rating=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/conversations/tickets/{conversation_id}/ai_feedback/".format(
        project_id=project_id,
		conversation_id="<the conversation id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"message_id": "string"
	}
).json()