AGNTDocs

Users and assistants

User setup

A user's profile and setup. Calls made as a user return `428 onboarding_required` until you set a timezone and working hours and mark setup complete.

GET/profile

Retrieve the user's profile

Retrieves the profile of the user named in `X-User-Email`. Works before the user finishes setup.

Responses

200Current user
okboolean
userobject
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
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
createdAtstring
updatedAtstring
401No user identified; send X-User-Email
404User not found

Request

curl 'https://api.agnt.ai/profile' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-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",
    "assistantName": "Ava"
  }
}
PATCH/profile

Update the user's profile

Updates the profile of the user named in `X-User-Email`. Only the fields you send change. Set `timezone` here before you mark setup complete.

Request body

firstNamestring
lastNamestring
timezonestringIANA timezone, such as America/New_York
localestring
citystring
countrystring | nullISO 3166-1 alpha-2; null clears
avatarstring
assistantstring | nullAssistant id to make the user's primary
voiceobject | nullnull clears
voiceIdstring
providerstringVoice engine

Responses

200Updated user
okboolean
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
providerIdstring | null
connectionRefstring | null
otherstring | null
assistantNamestring | null
appNamestring | null
createdAt reqstring
updatedAt reqstring
400Invalid timezone or country code
401No user identified
404User not found

Request

curl 'https://api.agnt.ai/profile' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Jane",
  "lastName": "Rivera",
  "timezone": "America/New_York",
  "locale": "locale"
}'

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"
  }
}
POST/onboarding/mark-onboarded

Complete user setup

Marks the user named in `X-User-Email` as set up, so calls made as that user stop returning `428 onboarding_required`. Set the timezone and working hours first. Calling it again has no effect.

Responses

200Marked
okboolean
401No user identified

Request

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

Response

{
  "ok": true
}
GET/users/{userId}/preferences/scheduling

Retrieve scheduling preferences

Retrieves the user's working hours, meeting defaults, calendars and buffers. With `X-User-Email`, `userId` must be the caller's own id.

Path parameters

userId reqstring

Responses

200Scheduling preferences
ok reqenumtrue
schedulingPreferences reqobject
availabilityobject
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
readstring[]
writestring
buffersobject
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
403With X-User-Email, the userId is not the caller's own

Request

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

Response

{
  "ok": true,
  "schedulingPreferences": {
    "availability": {
      "workingHours": {
        "MO": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TU": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "WE": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TH": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "FR": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ]
      }
    }
  }
}
PUT/users/{userId}/preferences/scheduling

Replace scheduling preferences

Replaces the user's working hours, meeting defaults, calendars and buffers. Retrieve the preferences first and send the whole object back with your change. With `X-User-Email`, `userId` must be the caller's own id.

Path parameters

userId reqstring

Request body

schedulingPreferences reqobject
availabilityobject
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
readstring[]
writestring
buffersobject
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring

Responses

200Saved preferences
ok reqenumtrue
schedulingPreferences reqobject
availabilityobject
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
readstring[]
writestring
buffersobject
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
400Invalid body, or working hours sent with no slots on any day
403With X-User-Email, the userId is not the caller's own

Request

curl 'https://api.agnt.ai/users/<userId>/preferences/scheduling' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "schedulingPreferences": {
    "availability": {
      "workingHours": {
        "MO": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TU": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "WE": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TH": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "FR": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ]
      }
    }
  }
}'

Response

{
  "ok": true,
  "schedulingPreferences": {
    "availability": {
      "workingHours": {
        "MO": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TU": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "WE": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "TH": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ],
        "FR": [
          {
            "start": "09:00",
            "end": "17:00"
          }
        ]
      }
    }
  }
}