Max API Reference

Max

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`

List all conversations

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"
  }
}