AGNTDocs

Users and assistants

Assistants

An assistant's identity: name, personality, writing style, email address and phone lines. A user can have several assistants, one of them primary.

GET/assistants

List assistants

Returns the assistants the caller can see, sorted by scope and name. Pass `email` to look one up by its address.

Query parameters

emailstring

Responses

200Assistants list
ok reqenumtrue
assistants reqobject[]
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring
pageinteger
perPageinteger
totalinteger

Request

curl 'https://api.agnt.ai/assistants' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistants": [
    {
      "id": "6702b4c1d2e3f4a5b6c7d8e9",
      "account": "66f1a2b3c4d5e6f708192a3b",
      "scope": "user",
      "user": "6702b1e8f9a0b1c2d3e4f5a6",
      "name": "Ava",
      "email": "[email protected]",
      "status": "active",
      "talkToStrangers": false,
      "createdAt": "2026-10-01T15:04:05Z"
    }
  ]
}
POST/assistants

Create an assistant

Creates an assistant. `scope` sets who can use it: `account` (every user of your app), `organization`, `team` or `user`. The email address must be free in your account.

Request body

name reqstring
email reqstring
scopeenumaccountorganizationteamuser
organizationstring | null
teamstring | null
personalitystring
signaturestring | null
signatureEditorModeenumvisualhtml
writingStyleobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
avatarstring | null
appearanceDescriptionstring
taglinestring | null
backstorystring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
metadataobject
talkToStrangersboolean
voiceobject | null
voiceIdstring | null
providerstring

Responses

201Created assistant
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring
400Bad request
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/assistants' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava",
  "email": "[email protected]"
}'

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
GET/assistants/{assistantId}

Retrieve an assistant

Retrieves an assistant's profile, email address, phone lines (`channels`), voice and scope.

Path parameters

assistantId reqstring

Responses

200Assistant
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
PUT/assistants/{assistantId}

Update an assistant

Updates an assistant. Only the fields you send change. To add a phone line, create a phone line request.

Path parameters

assistantId reqstring

Request body

namestringDisplay name
emailstringMailbox address; must be free in your account
personalitystringHow the assistant behaves and sounds
backstorystring | null
taglinestring | nullOne-line description shown with the assistant
writingStyleobjectTone sliders, 0 to 3
professionalismnumber
humornumber
emojiUsenumber
signaturestring | nullEmail signature
signatureEditorModeenumvisualhtml
avatarstring | nullImage URL or data URI
appearanceDescriptionstringWhat the assistant looks like, used for generated images
genderenummalefemaleothernull
pronounsstring | null
countrystring | nullTwo-letter country code
voiceobject | nullVoice engine and voice; see GET /voice/providers. null clears.
providerstringEngine id from GET /voice/providers
voiceIdstring | null
talkToStrangersbooleanWhether the assistant replies to people who are not users of your app
statusenumactiveinactive
metadataobjectYour own key-value data

Responses

200Updated assistant
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "personality": "Warm, brief and direct. Writes like a seasoned property manager.",
  "writingStyle": {
    "professionalism": 2,
    "humor": 1,
    "emojiUse": 0
  }
}'

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
DELETE/assistants/{assistantId}

Delete an assistant

Deletes an assistant and disconnects its mailboxes.

Path parameters

assistantId reqstring

Responses

200Deleted
ok reqenumtrue
assistant reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistant": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}
GET/users/{userId}/assistants

List a user's assistants

Returns every assistant on the user's roster, each marked `isPrimary`, plus `primaryAssistantId`.

Path parameters

userId reqstring

Responses

200Roster
ok reqenumtrue
assistants reqany[]
primaryAssistantId reqstring | null

Request

curl 'https://api.agnt.ai/users/<userId>/assistants' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistants": [
    {
      "id": "6702b4c1d2e3f4a5b6c7d8e9",
      "account": "66f1a2b3c4d5e6f708192a3b",
      "scope": "user",
      "user": "6702b1e8f9a0b1c2d3e4f5a6",
      "name": "Ava",
      "email": "[email protected]",
      "status": "active",
      "talkToStrangers": false,
      "createdAt": "2026-10-01T15:04:05Z",
      "isPrimary": true
    }
  ],
  "primaryAssistantId": "6660c4a1f2e3b7d8a9c01234"
}
POST/users/{userId}/assistants

Create an assistant for a user

Creates an assistant that belongs to the user and adds it to their roster. On an empty roster it becomes the primary. A second call with the same `name` returns the existing assistant with `200`.

Path parameters

userId reqstring

Request body

name reqstring
emailstring
avatarstring
signaturestring | null
signatureEditorModeenumvisualhtml
personalitystring
backstorystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
writingStyleobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
metadataobject
voiceobject | null
voiceIdstring | null
providerstring

Responses

200Already existed (idempotent); returned unchanged
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring
201Created and hired
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistants' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava"
}'

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
POST/users/{userId}/assistants/{assistantId}/hire

Add an assistant to a user

Adds an assistant the user can see to their roster. On an empty roster it also becomes the primary. Returns the updated user.

Path parameters

userId reqstring
assistantId reqstring

Responses

200Updated user
ok reqenumtrue
userobject
id reqstring
account reqstring
emailstring
externalIdstring
assistant reqstring | null
name reqstring | null
firstNamestring
lastNamestring
avatarUrl reqstring | null
timezone reqstring
locale reqstring
countrystring | null
citystring
organization reqstring | null
organizationRole reqenumadminmemberguest
team reqobject | null
id reqstring
name reqstring
organization reqstring | null
status reqstring
teamRole reqenummemberadminownernull
status reqenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesobject
remindersobject
levelenumWhich calendar events get reminders: all-events (every event), agnt-events (only events the assistant created), or none.all-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
403Assistant not visible to this user
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistants/<assistantId>/hire' \
  -X POST \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true
}
POST/users/{userId}/assistants/{assistantId}/primary

Set a user's primary assistant

Makes an assistant on the user's roster their primary, the one that answers by default. Returns the updated user.

Path parameters

userId reqstring
assistantId reqstring

Responses

200Updated user
ok reqenumtrue
userobject
id reqstring
account reqstring
emailstring
externalIdstring
assistant reqstring | null
name reqstring | null
firstNamestring
lastNamestring
avatarUrl reqstring | null
timezone reqstring
locale reqstring
countrystring | null
citystring
organization reqstring | null
organizationRole reqenumadminmemberguest
team reqobject | null
id reqstring
name reqstring
organization reqstring | null
status reqstring
teamRole reqenummemberadminownernull
status reqenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesobject
remindersobject
levelenumWhich calendar events get reminders: all-events (every event), agnt-events (only events the assistant created), or none.all-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
400Assistant not on roster
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistants/<assistantId>/primary' \
  -X POST \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true
}
DELETE/users/{userId}/assistants/{assistantId}

Remove an assistant from a user

Releases and deletes one of the user's personal assistants. To release an assistant that still has open tasks, pass `transfer=primary` to move that work to the primary assistant.

Path parameters

userId reqstring
assistantId reqstring

Query parameters

transferstring

Responses

200Released; returns the updated user
ok reqenumtrue
userobject
id reqstring
account reqstring
emailstring
externalIdstring
assistant reqstring | null
name reqstring | null
firstNamestring
lastNamestring
avatarUrl reqstring | null
timezone reqstring
locale reqstring
countrystring | null
citystring
organization reqstring | null
organizationRole reqenumadminmemberguest
team reqobject | null
id reqstring
name reqstring
organization reqstring | null
status reqstring
teamRole reqenummemberadminownernull
status reqenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesobject
remindersobject
levelenumWhich calendar events get reminders: all-events (every event), agnt-events (only events the assistant created), or none.all-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
403A shared or account-wide assistant, or one the caller may not release
statusinteger
error_codestring
errorstring
409Refused: the assistant is the primary, or has pending work
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistants/<assistantId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true
}
GET/users/{userId}/assistant

Retrieve a user's personal assistant

Retrieves the assistant created for this user, not a shared one. With `X-User-Email`, `userId` must be the caller.

Path parameters

userId reqstring

Responses

200User assistant
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistant' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
POST/users/{userId}/assistant

Create a user's personal assistant

Creates an assistant that belongs to this user. Returns `400` if the user already has one or the email address is taken.

Path parameters

userId reqstring

Request body

name reqstringDisplay name
emailstringMailbox address; generated when omitted
avatarstringImage URL or data URI
signaturestring | null
personalitystring
backstorystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | nullTwo-letter country code
writingStyleobject
professionalismnumber
humornumber
emojiUsenumber
metadataobject

Responses

201Created
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistant' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava"
}'

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
PUT/users/{userId}/assistant

Update a user's personal assistant

Updates the user's personal assistant. Only the fields you send change.

Path parameters

userId reqstring

Request body

namestringDisplay name
emailstringMailbox address; generated when omitted
avatarstringImage URL or data URI
signaturestring | null
personalitystring
backstorystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | nullTwo-letter country code
writingStyleobject
professionalismnumber
humornumber
emojiUsenumber
metadataobject

Responses

200Updated
ok reqenumtrue
assistant reqobject
id reqstring
account reqstring
organization reqstring | null
team reqstring | null
user reqstring | null
scope reqenumaccountorganizationteamuser
name reqstring
email reqstring
avatarUrl reqstring | null
signature reqstring | null
signatureEditorModeenumvisualhtml
personalitystring
taglinestring | null
backstorystring | null
rolestring | null
displayPersonalitystring | null
genderenummalefemaleothernull
pronounsstring | null
countrystring | null
signaturePhrasesstring[]
writingStyle reqobject
professionalismnumber
humornumber
emojiUsenumber
characterInspirationstring
externalCommunicationstring
oneOnOneCommunicationstring
voice reqobject | null
voiceIdstring | null
providerstring
status reqenumactiveinactive
talkToStrangers reqboolean
metadataobject
inboxPlatform reqenumgoogleoutlooknull
inboxAuthErrorboolean
channelsobject
imessagestring | null
smsstring | null
whatsappstring | null
voiceobject
statusenumnoneprovisioningpending_a2pactivefailed
provisionedAtstring | null
recordingDisclosureboolean
appearanceDescriptionstring
tagsobject
deletedAtstring | null
retiredEmailstring | null
emailReleasedAtstring | null
createdAt reqstring
updatedAt reqstring

Request

curl 'https://api.agnt.ai/users/<userId>/assistant' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava",
  "email": "[email protected]",
  "avatar": "avatar",
  "signature": "signature"
}'

Response

{
  "ok": true,
  "assistant": {
    "id": "6702b4c1d2e3f4a5b6c7d8e9",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "scope": "user",
    "user": "6702b1e8f9a0b1c2d3e4f5a6",
    "name": "Ava",
    "email": "[email protected]",
    "status": "active",
    "talkToStrangers": false,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
DELETE/users/{userId}/assistant

Delete a user's personal assistant

Deletes the user's personal assistant and disconnects its mailboxes.

Path parameters

userId reqstring

Responses

200Deleted
ok reqenumtrue
assistant reqobject
id reqstring
deletedboolean
messagestring

Request

curl 'https://api.agnt.ai/users/<userId>/assistant' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "assistant": {
    "id": "6660c4a1f2e3b7d8a9c01234"
  }
}
GET/assistants/{assistantId}/voice-greetings

Retrieve voice greetings

Retrieves the lines the assistant can open a call with. When none exist, generation starts in the background and the response says so.

Path parameters

assistantId reqstring

Responses

200Voice greetings
ok reqenumtrue
voiceGreetings reqobject
inbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
outbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
generatedAt reqstring | null
generating reqboolean
appliedboolean
reasonenumconcurrent_write
limits reqobject
minLines reqnumber
maxLines reqnumber
minChars reqnumber
maxChars reqnumber
maxSentences reqnumber
outboundPlaceholder reqstring
rules reqstring[]
generatedOnlyRules reqstring[]
403Not the assistant's owner
status reqinteger
error_codestring
error reqstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>/voice-greetings' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "voiceGreetings": {
    "inbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "outbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "generatedAt": "2026-10-15T14:30:00Z",
    "generating": true,
    "limits": {
      "minLines": 15,
      "maxLines": 1,
      "minChars": 15,
      "maxChars": 1,
      "maxSentences": 1,
      "outboundPlaceholder": "outboundplaceholder"
    }
  }
}
PUT/assistants/{assistantId}/voice-greetings

Update voice greetings

Saved lists are marked source "owner" and are never overwritten by generation. Outbound templates need exactly one {firstName}; inbound lines must have none. Never starts generation: after clearing a list ([]), the next GET starts it (at most once per 10 minutes per assistant).

Path parameters

assistantId reqstring

Request body

inboundstring[]
outboundstring[]

Responses

200Updated voice greetings
ok reqenumtrue
voiceGreetings reqobject
inbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
outbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
generatedAt reqstring | null
generating reqboolean
appliedboolean
reasonenumconcurrent_write
limits reqobject
minLines reqnumber
maxLines reqnumber
minChars reqnumber
maxChars reqnumber
maxSentences reqnumber
outboundPlaceholder reqstring
rules reqstring[]
generatedOnlyRules reqstring[]
400A line or list failed validation (error_code invalid_voice_greetings; body.details = {list, index?, reason})
status reqinteger
error_codestring
error reqstring
403Not the assistant's owner
status reqinteger
error_codestring
error reqstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>/voice-greetings' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "inbound": [
    "inbound"
  ],
  "outbound": [
    "outbound"
  ]
}'

Response

{
  "ok": true,
  "voiceGreetings": {
    "inbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "outbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "generatedAt": "2026-10-15T14:30:00Z",
    "generating": true,
    "limits": {
      "minLines": 15,
      "maxLines": 1,
      "minChars": 15,
      "maxChars": 1,
      "maxSentences": 1,
      "outboundPlaceholder": "outboundplaceholder"
    }
  }
}
GET/assistants/check-email

Check an assistant email address

Builds an address from `slug` (lowercase letters and digits) on your app's email domain and reports whether an assistant already uses it. Pass `excludeId` to ignore one assistant, such as the one you are renaming.

Query parameters

slug reqstringDesired local part; anything after @ is ignored
excludeIdstring

Responses

200Availability
available reqboolean
email reqstringThe full address checked
400slug is required

Request

curl 'https://api.agnt.ai/assistants/check-email?slug=' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "available": true,
  "email": "[email protected]"
}
GET/assistants/generate

Suggest an assistant name and email

Suggests an assistant name and three email addresses that are free in your account. Pass `name` to get addresses for that name.

Query parameters

namestring

Responses

200Generated suggestions
name reqstring
emails reqstring[]

Request

curl 'https://api.agnt.ai/assistants/generate' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "name": "Ava",
  "emails": [
    "[email protected]"
  ]
}
POST/assistants/{assistantId}/voice-greetings/regenerate

Regenerate voice greetings

Writes new opening lines from the assistant's personality. Limited to 5 calls per hour per assistant. Lines the owner edited are kept unless `replaceOwnerEdits` is `true`.

Path parameters

assistantId reqstring

Request body

scopeenumbothinboundoutbound
replaceOwnerEditsboolean

Responses

200Voice greetings after regeneration
ok reqenumtrue
voiceGreetings reqobject
inbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
outbound reqobject
lines reqstring[]
source reqenumgeneratedownernull
updatedAt reqstring | null
generatedAt reqstring | null
generating reqboolean
appliedboolean
reasonenumconcurrent_write
limits reqobject
minLines reqnumber
maxLines reqnumber
minChars reqnumber
maxChars reqnumber
maxSentences reqnumber
outboundPlaceholder reqstring
rules reqstring[]
generatedOnlyRules reqstring[]
403Not the assistant's owner
status reqinteger
error_codestring
error reqstring
404Not found
status reqinteger
error_codestring
error reqstring
409Generation already running (generation_in_progress), or every requested list is owner-written (owner_edited)
status reqinteger
error_codestring
error reqstring
429Too many regenerations for this assistant (body.retryAfterSeconds, Retry-After header)
status reqinteger
error_codestring
error reqstring
502The model could not produce valid lines (greeting_generation_failed)
status reqinteger
error_codestring
error reqstring
503The rate limiter is unavailable (rate_limit_unavailable); nothing was generated
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/assistants/<assistantId>/voice-greetings/regenerate' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "both",
  "replaceOwnerEdits": true
}'

Response

{
  "ok": true,
  "voiceGreetings": {
    "inbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "outbound": {
      "lines": [
        "line"
      ],
      "source": "generated",
      "updatedAt": "2026-10-15T14:30:00Z"
    },
    "generatedAt": "2026-10-15T14:30:00Z",
    "generating": true,
    "limits": {
      "minLines": 15,
      "maxLines": 1,
      "minChars": 15,
      "maxChars": 1,
      "maxSentences": 1,
      "outboundPlaceholder": "outboundplaceholder"
    }
  }
}
POST/assistants/{assistantId}/slack-apps

Create a Slack app for an assistant

Gives the assistant its own Slack app and returns the manifest to apply in Slack. `kind: "marketplace"` creates your listed app and requires an account key and an account-wide assistant. `kind: "workspace"` creates an app internal to the calling user's workspace and requires `X-User-Email`. Returns `201` for a new app and `200` for an existing one.

Path parameters

assistantId reqstring

Request body

kind reqenumRequired. marketplace: your listed app, for an account-wide assistant; call with an account key. workspace: an app internal to one Slack workspace, for a user's own or shared assistant; call as that user.marketplaceworkspace
botDisplayNamestring

Responses

200Existing app (201: new app, same shape)
okboolean
slackAppobject
idstring
assistantstring
kindenummarketplaceworkspace
slackAppIdstring | null
botDisplayNamestring | null
hasCredentialsboolean
statusenumpending_credentialsactivedisableddeleted
createdAtstring
manifestobject
manifestobject
manifestJsonstring
createAppUrlstring
eventsUrlstring
redirectUrlsstring[]
400Invalid input, or kind marketplace for an assistant that is not account-wide (not_system_assistant)
statusinteger
error_codestring
errorstring
403kind marketplace without an account key; kind workspace without a user (user_required), for an account-wide assistant (system_assistant_console_only), for a user without the assistant, or where Slack is off (slack_not_allowed)
statusinteger
error_codestring
errorstring
404Assistant not found
409already_exists

Request

curl 'https://api.agnt.ai/assistants/<assistantId>/slack-apps' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "marketplace"
}'

Response

{
  "ok": true,
  "slackApp": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "assistant": "assistant",
    "kind": "marketplace",
    "slackAppId": "6660c4a1f2e3b7d8a9c01234"
  },
  "manifest": {
    "manifest": {},
    "manifestJson": "manifestjson",
    "createAppUrl": "https://harborview.co",
    "eventsUrl": "https://harborview.co"
  }
}
GET/oauth/slack/assistant/authorize

Create an Add to Slack URL

Returns a Slack install URL for the assistant. Call it from your server as the user, then send the user's browser to `oauth.url`. After Slack, the browser returns to your app. The user must have the assistant, and their organization must allow Slack.

Query parameters

assistantId reqstring
hoststringYour app's hosted domain to return the browser to
assistantSlackAppIdstringA specific Slack app; defaults to the assistant's listed app

Responses

200URL to open in the user's browser
ok reqboolean
oauth reqobject
url reqstring
403user_required, no access to the assistant, or slack_not_allowed
404Assistant or slack_app_not_found
409credentials_missing

Request

curl 'https://api.agnt.ai/oauth/slack/assistant/authorize?assistantId=' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "oauth": {
    "url": "https://harborview.co"
  }
}
GET/oauth/slack/assistant/link

Create a Sign in with Slack URL

Returns a Slack sign-in URL that links the user's Slack identity, so the assistant recognizes them in Slack. Call it as the user and send the browser to `oauth.url`.

Query parameters

assistantId reqstring
hoststringYour app's hosted domain to return the browser to
assistantSlackAppIdstringA specific Slack app; defaults to the assistant's listed app

Responses

200URL to open in the user's browser
ok reqboolean
oauth reqobject
url reqstring
403user_required, no access to the assistant, or slack_not_allowed
404Assistant or slack_app_not_found
409credentials_missing

Request

curl 'https://api.agnt.ai/oauth/slack/assistant/link?assistantId=' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "oauth": {
    "url": "https://harborview.co"
  }
}
GET/slack/workspaces

List Slack workspaces

Returns the Slack workspaces where the user has linked or installed one of their assistants, with each assistant there.

Responses

200Workspaces
okboolean
slackAllowedbooleanWhether the user's organization allows Slack
slackWorkspacesobject[]
slackTeamIdstring
teamNamestring | null
domainstring | null
linkedbooleanTrue when the user has verified their Slack account in this workspace
assistantsobject[]
assistantIdstring
assistantNamestring | null
installIdstring
enabledboolean
installedByMeboolean
botDisplayNamestring | null
slackUserIdstring | null
openUrlstring | nullslack:// link to a direct message with the assistant
403user_required: call as a user

Request

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

Response

{
  "ok": true,
  "slackAllowed": true,
  "slackWorkspaces": [
    {
      "slackTeamId": "6660c4a1f2e3b7d8a9c01234",
      "teamName": "Ava",
      "domain": "harborview.co",
      "linked": true
    }
  ]
}
GET/oauth/teams/authorize

Create a Microsoft Teams connect URL

Returns a Microsoft sign-in URL that connects Teams messaging to an organization or team. Send the admin's browser to `oauth.url`. Called as a user, the user must be an admin of the target.

Query parameters

target reqstring
targetId reqstringOrganization or team id
hoststringYour app's hosted domain to return the browser to

Responses

200URL to open in the user's browser
ok reqboolean
oauth reqobject
url reqstring
400Missing target or targetId, or no Teams app configured
403Admin role required

Request

curl 'https://api.agnt.ai/oauth/teams/authorize?target=&targetId=' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "oauth": {
    "url": "https://harborview.co"
  }
}