Conversations API Reference

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`
`PATCH`
`DELETE`
`POST`
`GET`
`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
stringnull
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","null"],\
	-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",
			"null"
		],
		"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
stringnull
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","null"]
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",
			"null"
		]
	}
).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 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

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"
status
string
tags
string
tags_all
string
tags_exclude
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": null,
      "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
      ]
    }
  ]
}

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": null,
  "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
  ]
}

Update conversations tickets

Required API key scopes

ticket:write

Path parameters

id
string

Request parameters

status
priority
anonymous_traits
ai_resolved
boolean
escalation_reason
stringnull
sla_due_at
stringnull
snoozed_until
stringnull
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 ticket_number="integer"
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={
		"ticket_number": "integer"
	}
).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": null,
  "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
  ]
}

Delete conversations tickets

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()

Example response

Status 202 No response body

List all conversations tickets messages

Return the message thread for a ticket, ordered chronologically (paginated).

Required API key scopes

ticket:read

Path parameters

id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/conversations/tickets/:id/messages
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/messages/
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}/messages/".format(
        project_id=project_id,
		conversation_id="<the conversation 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",
      "content": "string",
      "rich_content": null,
      "author_type": "string",
      "author_name": "string",
      "is_private": true,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create conversations tickets reply

Post a reply or internal note to a ticket.

With is_private=false, the reply is delivered to the customer via the ticket's channel (email, Slack, Teams, GitHub). With is_private=true, the message is stored as an internal note only visible to team members.

Required API key scopes

ticket:write

Path parameters

id
string

Request parameters

message
string
is_private
boolean
Default: false
rich_content

Response

Example request

POST /api/projects/:project_id/conversations/tickets/:id/reply
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/reply/\
	-d message="string"
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}/reply/".format(
        project_id=project_id,
		conversation_id="<the conversation id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"message": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "content": "string",
  "rich_content": null,
  "author_type": "string",
  "author_name": "string",
  "is_private": true,
  "created_at": "2019-08-24T14:15:22Z"
}