AGNTDocs

Users and assistants

Users

The end users of your app. You provision users by email, and everything a user owns (tasks, chats, memories, contacts) is isolated to that user. Errors common to every user-scoped call are listed in the Authentication guide.

POST/users/provision

Provision a user

Finds the user with this email in your account, or creates one, and places them on a team. Pass `teamId` to choose the team; otherwise the user joins the default team. Returns `201` when the user is created and `200` when they already exist. Requires an account key.

Request body

idstring
email reqstring
teamIdstring
firstNamestring
lastNamestring

Responses

200Existing user
ok reqenumtrue
user reqobject
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
teamId reqstring
created reqbooleanTrue when a new user account was created (vs. an existing user found).
addedToTeam reqbooleanTrue when this call created a new team membership for the user.
alreadyMember reqbooleanTrue when nothing changed: the user and their team membership both already existed. Callers can surface an "already a member" message.
joinSkipped reqbooleanTrue when the user/org was provisioned but the team join was skipped because the user already owns a different team with other active members and no automatic conflict resolution was possible. Needs manual reconciliation (ownership transfer).
201Created user
ok reqenumtrue
user reqobject
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
teamId reqstring
created reqbooleanTrue when a new user account was created (vs. an existing user found).
addedToTeam reqbooleanTrue when this call created a new team membership for the user.
alreadyMember reqbooleanTrue when nothing changed: the user and their team membership both already existed. Callers can surface an "already a member" message.
joinSkipped reqbooleanTrue when the user/org was provisioned but the team join was skipped because the user already owns a different team with other active members and no automatic conflict resolution was possible. Needs manual reconciliation (ownership transfer).

Request

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

Response

{
  "ok": true,
  "user": {
    "id": "6702b1e8f9a0b1c2d3e4f5a6",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "email": "[email protected]",
    "name": "Jane Rivera",
    "firstName": "Jane",
    "lastName": "Rivera",
    "timezone": "America/Los_Angeles",
    "status": "active",
    "organization": null,
    "createdAt": "2026-10-01T15:04:05Z"
  },
  "teamId": "6702ab52c3d4e5f6a7b8c9d0",
  "created": false,
  "addedToTeam": false,
  "alreadyMember": true,
  "joinSkipped": false
}
POST/users/deprovision

Deprovision a user

Removes the user with this email from one team. When the user has no team left, the user and all of their data are deleted and `userDeleted` is `true`. The organization's only admin returns `409` with `requiresOrgAdminTransfer`, and the owner of a team with other active members returns `400` with `requiresOwnershipTransfer`.

Request body

email reqstring
teamId reqstring

Responses

200Result
ok reqenumtrue
deleted reqboolean
userDeletedboolean
userIdstring
messagestring

Request

curl 'https://api.agnt.ai/users/deprovision' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "teamId": "6660c4a1f2e3b7d8a9c01234"
}'

Response

{
  "ok": true,
  "deleted": false
}
GET/users

List users

Returns the users in your account, newest first. Filter by `status`, `email`, `externalId` or `organizationId`; `search` matches name and email.

Query parameters

pageinteger
perPageinteger
statusstring
emailstring
externalIdstring
organizationIdstring
searchstring

Responses

200Paginated user list
ok reqenumtrue
users reqobject[]
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
remindersany
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
pageinteger
perPageinteger
totalinteger

Request

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

Response

{
  "ok": true,
  "users": [
    {
      "id": "6702b1e8f9a0b1c2d3e4f5a6",
      "account": "66f1a2b3c4d5e6f708192a3b",
      "email": "[email protected]",
      "name": "Jane Rivera",
      "firstName": "Jane",
      "lastName": "Rivera",
      "timezone": "America/Los_Angeles",
      "status": "active",
      "organization": null,
      "createdAt": "2026-10-01T15:04:05Z"
    }
  ]
}
GET/users/{userId}

Retrieve a user

Retrieves a user's profile, organization, role, team and status.

Path parameters

userId reqstring

Responses

200User detail
ok reqenumtrue
user reqobject
idstring
accountstring
emailstring
externalIdstring
assistantstring | null
namestring | null
firstNamestring
lastNamestring
avatarUrlstring | null
timezonestring
localestring
countrystring | null
citystring
organizationstring | null
organizationRoleenumadminmemberguest
teamobject | null
id reqstring
name reqstring
organization reqstring | null
status reqstring
teamRoleenummemberadminownernull
statusenumactiveinactivesuspended
voiceobject | null
voiceId reqstring
provider reqstring
metadataobject
firstLoginAtstring
usernamestring | null
preferencesobject
remindersany
preferredProvidersobject
preferredContactChannelobject
assistantNamestring | null
appNamestring | null
createdAtstring
updatedAtstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

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

Response

{
  "ok": true,
  "user": {
    "id": "6702b1e8f9a0b1c2d3e4f5a6",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "email": "[email protected]",
    "name": "Jane Rivera",
    "firstName": "Jane",
    "lastName": "Rivera",
    "timezone": "America/Los_Angeles",
    "status": "active",
    "organization": null,
    "createdAt": "2026-10-01T15:04:05Z",
    "identifiers": [
      {
        "id": "6702b65ac1d2e3f4a5b6c7d8",
        "type": "email",
        "value": "[email protected]",
        "verified": true,
        "primary": true,
        "createdAt": "2026-10-01T15:04:05Z"
      }
    ]
  }
}
PUT/users/{userId}

Update a user

Updates a user's profile fields and organization role. With organization-scoped credentials, the user must belong to the same organization.

Path parameters

userId reqstring

Request body

namestring
firstNamestring
lastNamestring
avatarstring
timezonestring
localestring
statusenumactiveinactivesuspended
externalIdstring
assistantEmailstring | null
organizationstring | null
organizationRoleenumadminmemberguest
metadataobject

Responses

200Updated user
ok reqenumtrue
user reqobject
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
403User does not belong to your organization

Request

curl 'https://api.agnt.ai/users/<userId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ava",
  "firstName": "Jane",
  "lastName": "Rivera",
  "avatar": "avatar"
}'

Response

{
  "ok": true,
  "user": {
    "id": "6702b1e8f9a0b1c2d3e4f5a6",
    "account": "66f1a2b3c4d5e6f708192a3b",
    "email": "[email protected]",
    "name": "Jane Rivera",
    "firstName": "Jane",
    "lastName": "Rivera",
    "timezone": "America/Los_Angeles",
    "status": "active",
    "organization": null,
    "createdAt": "2026-10-01T15:04:05Z"
  }
}
DELETE/users/{userId}

Delete a user

Deletes a user and all of their data. The `200` response confirms that deletion is scheduled; the data is removed in the background. To cut off access first, set `status` to `suspended`. Requires an account key or an organization admin.

Path parameters

userId reqstring

Responses

200Deletion scheduled
ok reqenumtrue
user reqobject
idstring
deletedenumtrue
messagestringSays the deletion is scheduled and running in the background
400The user owns a team that still has other active members. Transfer ownership first.
okenumfalse
errorstring
requiresOwnershipTransferenumtrue
teamIdstring
403Not an organization admin
statusinteger
error_codestring
errorstring
404User not found
statusinteger
error_codestring
errorstring
409The user is the only admin of their organization. Promote another admin first.
okenumfalse
errorstring
requiresOrgAdminTransferenumtrue
organizationIdstring

Request

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

Response

{
  "ok": true,
  "user": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "deleted": true,
    "message": "Prefers morning meetings."
  }
}