AGNTDocs

Work

Chats

Conversations between a user and an assistant. Add a message, then process the chat to get the assistant's reply.

GET/chats

List chats

Returns the user's chats, most recent first.

Query parameters

pageinteger
perPageinteger
statusstring
assistantIdstring
qstringSearch
platformstringChannel, one value or comma-separated: chat, email, slack, teams, sms, whatsapp, imessage, phone
userEmailstringWith an account key and no X-User-Email: only chats of the user with this email

Responses

200Chats
okboolean
chatsobject[]
id reqstringChat id
titlestring | null
status reqenumactivearchived
platformenumChannel of the conversation; chat is an in-app chatchatemailslackteamssmswhatsappimessagercsphonediscordtelegramtask_activity
userstringUser id
ownerobject
idstring
emailstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstringAssistant id
assistantInfoobject
idstring
namestring
emailstring
participantsobject[]
typeenumphoneemail
valuestring
messageCountnumber
lastMessageAtstring | null
createdForTaskIdstring | nullSet when the chat was opened for a task
tagsstring[]
metadataobject
modelTierenumlowmediumhighultra
effortenumReasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max.lowmediumhighxhighmax
createdAtstring
updatedAtstring
pageinteger
perPageinteger
totalinteger

Request

curl 'https://api.agnt.ai/chats' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "chats": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "status": "active"
    }
  ],
  "page": 1,
  "perPage": 20
}
POST/chats

Create a chat

Creates a chat between the user and one of their assistants.

Request body

assistantId reqstringAssistant id
titlestring
metadataobjectYour own key-value data
modelTierenumDefaults to the organization's chat tier, then the account's, then medium.lowmediumhighultra

Responses

201Chat
okboolean
chatobject
id reqstringChat id
titlestring | null
status reqenumactivearchived
platformenumChannel of the conversation; chat is an in-app chatchatemailslackteamssmswhatsappimessagercsphonediscordtelegramtask_activity
userstringUser id
ownerobject
idstring
emailstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstringAssistant id
assistantInfoobject
idstring
namestring
emailstring
participantsobject[]
typeenumphoneemail
valuestring
messageCountnumber
lastMessageAtstring | null
createdForTaskIdstring | nullSet when the chat was opened for a task
tagsstring[]
metadataobject
modelTierenumlowmediumhighultra
effortenumReasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max.lowmediumhighxhighmax
createdAtstring
updatedAtstring
400assistantId or user missing

Request

curl 'https://api.agnt.ai/chats' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "assistantId": "6702b1e8f9a0b1c2d3e4f5a6"
}'

Response

{
  "ok": true,
  "chat": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "status": "active"
  }
}
GET/chats/{chatId}

Retrieve a chat

Retrieves a chat's channel, user, assistant, participants and message count.

Path parameters

chatId reqstring

Responses

200Chat
okboolean
chatobject
id reqstringChat id
titlestring | null
status reqenumactivearchived
platformenumChannel of the conversation; chat is an in-app chatchatemailslackteamssmswhatsappimessagercsphonediscordtelegramtask_activity
userstringUser id
ownerobject
idstring
emailstring
firstNamestring | null
lastNamestring | null
avatarstring | null
assistantstringAssistant id
assistantInfoobject
idstring
namestring
emailstring
participantsobject[]
typeenumphoneemail
valuestring
messageCountnumber
lastMessageAtstring | null
createdForTaskIdstring | nullSet when the chat was opened for a task
tagsstring[]
metadataobject
modelTierenumlowmediumhighultra
effortenumReasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max.lowmediumhighxhighmax
createdAtstring
updatedAtstring
404Chat not found

Request

curl 'https://api.agnt.ai/chats/<chatId>' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "chat": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "status": "active"
  }
}
DELETE/chats/{chatId}

Delete a chat

Deletes a chat.

Path parameters

chatId reqstring

Responses

200Deleted
ok reqenumtrue
chat reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://api.agnt.ai/chats/<chatId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "chat": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}
POST/chats/{chatId}/messages

Create a message

Adds a message to a chat without running the assistant. To get a reply, process the chat.

Path parameters

chatId reqstring

Request body

content reqstringMessage text.
rolestring
fromstring
tostring | array
ccstring | array
subjectstring
platformstring
referenceIdstringYour own correlation id.
filesobject[]
metadataobject

Responses

200Saved message
okboolean
messageobject
idstring
rolestring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
contentstring
timestampstring
metadataobject
400content is required.
404Chat not found for this user.

Request

curl 'https://api.agnt.ai/chats/<chatId>/messages' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Prefers morning meetings."
}'

Response

{
  "ok": true,
  "message": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "role": "role",
    "from": "from",
    "to": [
      "to"
    ]
  }
}
GET/chats/{chatId}/messages

List messages

Returns a chat's messages, paginated.

Path parameters

chatId reqstring

Query parameters

pageinteger
perPageinteger

Responses

200Messages
ok reqenumtrue
messages reqobject[]
id reqstring
referenceIdstring
role reqstring
fromstring
tostring[]
ccstring[]
subjectstring
platformstring
content reqstring
filesany[]
timestamp reqstring
metadataobject
deliveryobjectDelivery state of an outbound assistant message. Read-only.
stateenumstaged: waiting in an approval (cart) and not sent yet. held: held back and not sent. provider_accepted: sent; the delivery service accepted it. unknown: AGNT has no confirmed delivery record, so do not assume it was or was not delivered. Other values describe messages that stayed inside AGNT, such as a reply shown only in the hosted app or a report between the assistant's own runs.stagedheldprovider_acceptedunknown
taskIdstringTask that sent it
cartIdstringApproval it went through, if any
pageinteger
perPageinteger
totalinteger

Request

curl 'https://api.agnt.ai/chats/<chatId>/messages' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "messages": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "role": "role",
      "content": "Prefers morning meetings.",
      "timestamp": "2026-10-15T14:30:00Z"
    }
  ]
}
POST/chats/{chatId}/process

Process a chat

Runs the assistant on the chat and streams the result as `text/event-stream`: `status_update` and `interim_message` events during the run, then a `message` event with the reply or an `error` event. The HTTP status is `200` even when an `error` event is sent. Events can arrive together when the run ends.

Path parameters

chatId reqstring

Request body

messageobjectSaves this as a user message, then runs. Must be an object with content; a bare string is ignored.
content reqstring
fromstring
tostring | array
ccstring | array
subjectstring
platformstring
referenceIdstring
filesobject[]Attachments: files already in the user's drive
fileId reqstringDrive file id (24 hex characters)
filenamestring
mimeTypestring
metadataobject
triggeringActivityIdstringId of an already-saved message to respond to.

Responses

200text/event-stream of status_update, interim_message, message and error events.

Request

curl 'https://api.agnt.ai/chats/<chatId>/process' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "content": "What is still open on the Brightline renewal?"
  }
}'
GET/chats/{chatId}/usage

Retrieve a chat's usage

Returns the tokens the chat used, per run and in total, and the credits charged for each run.

Path parameters

chatId reqstring

Responses

200Usage
totalobject
inputTokensnumber
outputTokensnumber
cacheReadTokensnumber
cacheCreationTokensnumber
totalTokensnumber
runsinteger
turnsinteger
rowsobject[]One row per run and model, oldest first
runIdstring | null
seqinteger
modelTierstring | null
inputTokensnumber
outputTokensnumber
cacheReadTokensnumber
cacheCreationTokensnumber
totalTokensnumber
turnsinteger
startedAtstring | null
creditsobjectCredits charged, one entry per run
totalnumber
runsobject[]
chargedCreditsnumber
isBillableboolean
createdAtstring
404Chat not found

Request

curl 'https://api.agnt.ai/chats/<chatId>/usage' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "total": {
    "inputTokens": 1840,
    "outputTokens": 1840,
    "cacheReadTokens": 1840,
    "cacheCreationTokens": 1840
  },
  "rows": [
    {
      "runId": "6660c4a1f2e3b7d8a9c01234",
      "seq": 1,
      "modelTier": "modeltier",
      "inputTokens": 1840
    }
  ],
  "credits": {
    "total": 42,
    "runs": [
      {
        "chargedCredits": 5,
        "isBillable": true,
        "createdAt": "2026-10-15T14:30:00Z"
      }
    ]
  }
}