Max API Reference

Max

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

Endpoints

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

List all conversations

Required API key scopes

conversation:read

Path parameters

project_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/environments/:project_id/conversations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/conversations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{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",
      "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": {
          "property1": null,
          "property2": null
        },
        "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": [
        {
          "property1": null,
          "property2": null
        }
      ],
      "has_unsupported_content": true,
      "agent_mode": "string",
      "pending_approvals": [
        {
          "property1": null,
          "property2": null
        }
      ]
    }
  ]
}

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

Path parameters

project_id
string

Request parameters

content
string
conversation
string
contextual_tools
object
ui_context
billing_context
trace_id
string
session_id
string
agent_mode
resume_payload

Response

Example request

POST /api/environments/: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/environments/: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/environments/{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": {
    "property1": null,
    "property2": null
  },
  "ui_context": null,
  "billing_context": null,
  "trace_id": "df570c03-5a03-4cea-8df0-c162d05127ac",
  "session_id": "string",
  "agent_mode": "product_analytics",
  "resume_payload": null
}

Retrieve conversations

Required API key scopes

conversation:read

Path parameters

conversation
string
project_id
string

Response

Example request

GET /api/environments/: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/environments/:project_id/conversations/:conversation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

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
project_id
string

Request parameters

content
string

Response

Example request

POST /api/environments/: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/environments/: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/environments/{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

Path parameters

conversation
string
project_id
string

Request parameters

Response

Example request

PATCH /api/environments/: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/environments/: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/environments/{project_id}/conversations/{conversation}/cancel/".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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Retrieve conversations queue

Path parameters

conversation
string
project_id
string

Response

Example request

GET /api/environments/: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/environments/:project_id/conversations/:conversation/queue/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Create conversations queue

Path parameters

conversation
string
project_id
string

Request parameters

Response

Example request

POST /api/environments/: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/environments/: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/environments/{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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Update conversations queue

Path parameters

conversation
string
project_id
string
queue_id
string

Request parameters

Response

Example request

PATCH /api/environments/: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/environments/: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/environments/{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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Delete conversations queue

Path parameters

conversation
string
project_id
string
queue_id
string

Example request

DELETE /api/environments/: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/environments/: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/environments/{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
project_id
string

Request parameters

Response

Example request

POST /api/environments/: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/environments/: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/environments/{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",
  "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": {
      "property1": null,
      "property2": null
    },
    "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": [
    {
      "property1": null,
      "property2": null
    }
  ],
  "has_unsupported_content": true,
  "agent_mode": "string",
  "pending_approvals": [
    {
      "property1": null,
      "property2": null
    }
  ]
}

Max

Endpoints

List all conversations

Required API key scopes

Path parameters

Query parameters

Response

Example request

Example response

Status 200

Create conversations

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 201

Retrieve conversations

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Create conversations append message

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Update conversations cancel

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Retrieve conversations queue

Path parameters

Response

Example request

Example response

Status 200

Create conversations queue

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Update conversations queue

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete conversations queue

Path parameters

Example request

Example response

Status 204 No response body

Create conversations queue clear

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Community questions