OpenAssistantAPI
→

User API

Chats

Conversation threads and messages

GET/chats

List chats

Query parameters

pageinteger
perPageinteger
limitinteger
statusstring
assistantIdstring
contextIdstring
qstring

Responses

200Chats
ok reqenumtrue
chats reqobject[]
id reqstring
account reqstring
userstring
ownerobject
id reqstring
type reqenumuser
email reqstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstring
assistantInfoobject
id reqstring
name reqstring
email reqstring
platform reqenumchatemailslackteamssmswhatsappimessagephonediscordtelegramtask_activity
titlestring | null
status reqstring
messageCount reqnumber
lastMessageAtstring | null
taskIdsstring[]
fileIdsstring[]
pendingHandoffobject | null
from reqstring
at reqstring | null
tagsstring[]
metadataobject
participantsobject[]
type reqenumphoneemail
value reqstring
modelTierenumlowmediumhigh
effortenumlowmediumhigh
usageobject
inputTokensnumber
outputTokensnumber
cacheReadTokensnumber
cacheCreationTokensnumber
costUsdnumber
runsnumber
turnsnumber
creditUsageobject | null
consumednumber
blockedAtstring | null
lastPauseNotifiedAtstring | null
createdAt reqstring
updatedAt reqstring
messagesobject[]
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
releasedRRobject[]
id reqstring
notestring
atstring
pageinteger
perPageinteger
totalinteger

Request

curl 'https://app.openassistant.us/api/chats' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "chats": [
    {
      "id": "string",
      "account": "string",
      "platform": "chat",
      "status": "string",
      "messageCount": 0,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}
POST/chats

Create a chat

Request body

assistantId reqstring
userIdstring
titlestring
metadataobject
contextIdstring

Responses

201Created
ok reqenumtrue
chat reqobject
id reqstring
account reqstring
userstring
ownerobject
id reqstring
type reqenumuser
email reqstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstring
assistantInfoobject
id reqstring
name reqstring
email reqstring
platform reqenumchatemailslackteamssmswhatsappimessagephonediscordtelegramtask_activity
titlestring | null
status reqstring
messageCount reqnumber
lastMessageAtstring | null
taskIdsstring[]
fileIdsstring[]
pendingHandoffobject | null
from reqstring
at reqstring | null
tagsstring[]
metadataobject
participantsobject[]
type reqenumphoneemail
value reqstring
modelTierenumlowmediumhigh
effortenumlowmediumhigh
usageobject
inputTokensnumber
outputTokensnumber
cacheReadTokensnumber
cacheCreationTokensnumber
costUsdnumber
runsnumber
turnsnumber
creditUsageobject | null
consumednumber
blockedAtstring | null
lastPauseNotifiedAtstring | null
createdAt reqstring
updatedAt reqstring
messagesobject[]
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
releasedRRobject[]
id reqstring
notestring
atstring

Request

curl 'https://app.openassistant.us/api/chats' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "assistantId": "string"
}'

Response

{
  "ok": true,
  "chat": {
    "id": "string",
    "account": "string",
    "platform": "chat",
    "status": "string",
    "messageCount": 0,
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}
GET/chats/{chatId}

Get a chat

Path parameters

chatId reqstring

Responses

200Chat
ok reqenumtrue
chat reqobject
id reqstring
account reqstring
userstring
ownerobject
id reqstring
type reqenumuser
email reqstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstring
assistantInfoobject
id reqstring
name reqstring
email reqstring
platform reqenumchatemailslackteamssmswhatsappimessagephonediscordtelegramtask_activity
titlestring | null
status reqstring
messageCount reqnumber
lastMessageAtstring | null
taskIdsstring[]
fileIdsstring[]
pendingHandoffobject | null
from reqstring
at reqstring | null
tagsstring[]
metadataobject
participantsobject[]
type reqenumphoneemail
value reqstring
modelTierenumlowmediumhigh
effortenumlowmediumhigh
usageobject
inputTokensnumber
outputTokensnumber
cacheReadTokensnumber
cacheCreationTokensnumber
costUsdnumber
runsnumber
turnsnumber
creditUsageobject | null
consumednumber
blockedAtstring | null
lastPauseNotifiedAtstring | null
createdAt reqstring
updatedAt reqstring
messagesobject[]
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
releasedRRobject[]
id reqstring
notestring
atstring

Request

curl 'https://app.openassistant.us/api/chats/<chatId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "chat": {
    "id": "string",
    "account": "string",
    "platform": "chat",
    "status": "string",
    "messageCount": 0,
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}
POST/chats/{chatId}

Add message to chat

Path parameters

chatId reqstring

Request body

referenceIdstring
rolestring
fromstring
tostring | array
ccstring | array
subjectstring
platformstring
content reqstring
filesany[]
metadataobject

Responses

200Message
ok reqenumtrue
message reqobject
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject

Request

curl 'https://app.openassistant.us/api/chats/<chatId>' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string"
}'

Response

{
  "ok": true,
  "message": {
    "id": "string",
    "role": "string",
    "content": "string",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
DELETE/chats/{chatId}

Delete a chat

Path parameters

chatId reqstring

Responses

200Deleted
ok reqenumtrue
chat reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://app.openassistant.us/api/chats/<chatId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "chat": {
    "id": "string"
  }
}
GET/chats/{chatId}/usage

Per-run usage breakdown for a chat (Trace rollup grouped by run + model)

Path parameters

chatId reqstring

Responses

200Usage rollup
total reqobject
inputTokens reqnumber
outputTokens reqnumber
cacheReadTokens reqnumber
cacheCreationTokens reqnumber
totalTokens reqnumber
costUsd reqnumber
runs reqinteger
turns reqinteger
rows reqobject[]
runId reqstring | null
runType reqstring | null
runLabel reqstring | null
seq reqinteger
model reqstring | null
provider reqstring | null
inputTokens reqnumber
outputTokens reqnumber
cacheReadTokens reqnumber
cacheCreationTokens reqnumber
totalTokens reqnumber
costUsd reqnumber
turns reqinteger
startedAt reqstring | null
modelTierstring | null
northStarProductnumber
creditsobject
total reqnumber
costsByType reqobject
runs reqobject[]
runKind reqstring | null
multiplier reqnumber
chargedCredits reqnumber
hardCogsUsd reqnumber
isBillable reqboolean
createdAt reqstring
costsByType reqany...
runShapeobject
runs reqnumber
turnsPerRun reqnumber
toolCallsPerTurn reqnumber
toolCallSum reqnumber
toolTurnCount reqnumber
subtaskSpawnsByProfile reqobject
research reqnumber
worker reqnumber
custom reqnumber
tierMix reqobject
low reqnumber
medium reqnumber
high reqnumber
continueCount reqnumber
subtaskDepth reqnumber
researchNoteCount reqnumber
researchNoteChars reqnumber
releasedBigResults reqnumber
unreleasedBigResults reqnumber
autoManagedBigResultsnumber
releaseRationumber | null
status reqstring | null
wallClockMs reqnumber | null
costUsd reqnumber
northStarProductnumber

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/usage' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "total": {
    "inputTokens": 0,
    "outputTokens": 0,
    "cacheReadTokens": 0,
    "cacheCreationTokens": 0,
    "totalTokens": 0,
    "costUsd": 0
  },
  "rows": [
    {
      "runId": "string",
      "runType": "string",
      "runLabel": "string",
      "seq": 0,
      "model": "string",
      "provider": "string"
    }
  ]
}
GET/chats/{chatId}/messages

List chat messages

Path parameters

chatId reqstring

Query parameters

pageinteger
perPageinteger
limitinteger

Responses

200Messages
ok reqenumtrue
messages reqobject[]
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
pageinteger
perPageinteger
totalinteger

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/messages' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "messages": [
    {
      "id": "string",
      "role": "string",
      "content": "string",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ]
}
DELETE/chats/{chatId}/messages

Clear all messages

Path parameters

chatId reqstring

Responses

200Cleared
ok reqenumtrue
clearMessages reqobject
success reqboolean
cleared reqboolean
chatId reqstring

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/messages' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "clearMessages": {
    "success": true,
    "cleared": true,
    "chatId": "string"
  }
}
GET/chats/{chatId}/messages/{messageId}

Get a message

Path parameters

chatId reqstring
messageId reqstring

Responses

200Message
ok reqenumtrue
message reqobject
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/messages/<messageId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "message": {
    "id": "string",
    "role": "string",
    "content": "string",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
PUT/chats/{chatId}/messages/{messageId}

Update a message

Path parameters

chatId reqstring
messageId reqstring

Request body

contentstring
filesany[]
metadataobject

Responses

200Updated
ok reqenumtrue
message reqobject
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/messages/<messageId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string",
  "files": [
    null
  ],
  "metadata": {}
}'

Response

{
  "ok": true,
  "message": {
    "id": "string",
    "role": "string",
    "content": "string",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}
DELETE/chats/{chatId}/messages/{messageId}

Delete a message

Path parameters

chatId reqstring
messageId reqstring

Responses

200Deleted
ok reqenumtrue
message reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/messages/<messageId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "message": {
    "id": "string"
  }
}
POST/chats/{chatId}/process

Process chat (trigger AI)

Path parameters

chatId reqstring

Responses

200Result
ok reqenumtrue
messageobject
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
taskIdsstring[]
processingany

Request

curl 'https://app.openassistant.us/api/chats/<chatId>/process' \
  -X POST \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true
}