AGNTDocs

Work

Autonomy

Per-user settings for how freely the assistant acts on each kind of outbound action (`auto`, `time-boxed` or `manual`), plus per-recipient exceptions. A team, organization or the account can lock a setting so lower levels can only tighten it.

GET/users/{userId}/preferences/supervision/matrix

Retrieve autonomy settings

Returns, for each kind of outbound action, whether the assistant acts on its own (`auto`), waits out a review window (`time-boxed`) or needs approval (`manual`), and which settings a team, organization or the account has locked. With `X-User-Email`, `userId` must be the caller.

Path parameters

userId reqstring

Responses

200Autonomy settings
okboolean
supervisionMatrixobject
matrixobject | nullAction types: email_as_user (email from the user's mailbox), email_as_assistant (email from the assistant's mailbox), messaging (texts and chat messages), voice_call_as_assistant, voice_call_as_user, calendar, files, drive, contacts, third_party_skills (actions in connected apps), website.
email_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
email_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
messagingobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
calendarobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
filesobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
driveobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
contactsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
third_party_skillsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
websiteobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
lockedstring[]Read-only here; set by admins
exceptionsobject[]
idstringException id
labelstring | null
matchobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
modeenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send
createdAtstring
matrixUpdatedAtstring | null
parentLockedCellsstring[]Locked by any team, organization or the account
orgLockedCellsstring[]
teamLockedCellsstring[]
lockedValuesobjectAction type to the { mode, timeBoxedWindowMin } it is pinned to
403With X-User-Email, the userId is not the caller's own
428User has not finished setup

Request

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

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "email_as_user": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "email_as_assistant": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "messaging": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "voice_call_as_assistant": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      }
    },
    "matrixUpdatedAt": "2026-10-15T14:30:00Z",
    "parentLockedCells": [
      "parentlockedcell"
    ],
    "orgLockedCells": [
      "orglockedcell"
    ]
  }
}
PATCH/users/{userId}/preferences/supervision/matrix

Update autonomy settings

Merges the cells you send into the user's autonomy settings. Sending `exceptions` replaces the whole list (up to 100). A change that loosens a setting a team, organization or the account locked returns `403`.

Path parameters

userId reqstring

Request body

matrix reqobjectAction types: email_as_user (email from the user's mailbox), email_as_assistant (email from the assistant's mailbox), messaging (texts and chat messages), voice_call_as_assistant, voice_call_as_user, calendar, files, drive, contacts, third_party_skills (actions in connected apps), website. Each is a cell; exceptions replaces the whole list. locked is not accepted here (400).
email_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
email_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
messagingobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
calendarobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
filesobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
driveobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
contactsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
third_party_skillsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
websiteobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
exceptionsobject[]
labelstring | null
match reqobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
mode reqenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send

Responses

200Updated
okboolean
supervisionMatrixobject
matrixobjectAction types: email_as_user (email from the user's mailbox), email_as_assistant (email from the assistant's mailbox), messaging (texts and chat messages), voice_call_as_assistant, voice_call_as_user, calendar, files, drive, contacts, third_party_skills (actions in connected apps), website.
email_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
email_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
messagingobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
calendarobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
filesobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
driveobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
contactsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
third_party_skillsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
websiteobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
lockedstring[]Read-only here; set by admins
exceptionsobject[]
idstringException id
labelstring | null
matchobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
modeenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send
createdAtstring
matrixUpdatedAtstring
400Invalid body, locked sent in the body, or an invalid exception
403Locked by a parent level, or caller may not edit this user
404No preferences for this user

Request

curl 'https://api.agnt.ai/users/<userId>/preferences/supervision/matrix' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "matrix": {
    "email_as_assistant": {
      "mode": "time-boxed",
      "timeBoxedWindowMin": 10
    }
  }
}'

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "email_as_user": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "email_as_assistant": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "messaging": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      },
      "voice_call_as_assistant": {
        "mode": "auto",
        "timeBoxedWindowMin": 15,
        "timeBoxedExpiry": "execute",
        "undoDelaySec": 30
      }
    },
    "matrixUpdatedAt": "2026-10-15T14:30:00Z"
  }
}
PUT/users/{userId}/preferences/supervision/matrix/reset

Reset autonomy settings

Clears the user's own cells and deletes their recipient exceptions. Each action type then follows the team or organization value, or the platform default: `manual` for `email_as_user`, `voice_call_as_user`, `third_party_skills` and `website`, and `auto` for the rest. Locks set above the user stay in force.

Path parameters

userId reqstring

Responses

200Default settings
okboolean
supervisionMatrixobject
matrixobjectAction types: email_as_user (email from the user's mailbox), email_as_assistant (email from the assistant's mailbox), messaging (texts and chat messages), voice_call_as_assistant, voice_call_as_user, calendar, files, drive, contacts, third_party_skills (actions in connected apps), website.
email_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
email_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
messagingobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_assistantobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
voice_call_as_userobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
calendarobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
filesobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
driveobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
contactsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
third_party_skillsobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
websiteobject
modeenumauto: acts on its own. time-boxed: waits out a window in which the user can stop it. manual: waits for approval.autotime-boxedmanualnull
timeBoxedWindowMinnumber | nullWindow length in minutes, for time-boxed
timeBoxedExpiryenumWhat happens when the window endsexecutecancelnull
undoDelaySecnumber | nullSeconds an action that cannot be reversed (a sent message, a call) waits after it is released, before it goes out. Undo during this hold cancels it. 0 sends at once; unset uses the default of 30.
lockedstring[]Read-only here; set by admins
exceptionsobject[]
idstringException id
labelstring | null
matchobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
modeenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send
createdAtstring
matrixUpdatedAtstring
403Caller may not edit this user
404No preferences for this user

Request

curl 'https://api.agnt.ai/users/<userId>/preferences/supervision/matrix/reset' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "locked": [],
      "email_as_user": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "email_as_assistant": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "messaging": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "voice_call_as_assistant": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "voice_call_as_user": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "calendar": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "files": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "drive": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "contacts": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "third_party_skills": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      },
      "website": {
        "mode": null,
        "timeBoxedWindowMin": null,
        "timeBoxedExpiry": null,
        "undoDelaySec": null
      }
    },
    "matrixUpdatedAt": "2026-10-10T14:30:00Z"
  }
}
POST/users/{userId}/preferences/supervision/exceptions

Create a recipient exception

Adds a per-recipient override, such as always requiring approval for an email address or domain. Applies only to actions that have a recipient. A user can have up to 100 exceptions.

Path parameters

userId reqstring

Request body

labelstring | null
match reqobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
mode reqenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send

Responses

201Created
okboolean
recipientExceptionobject
idstringException id
labelstring | null
matchobject
kind reqenumemail or domain match a recipient; tag, priority, company and contactId match a contact; internal matches people in the user's organization; connection matches a connected app.tagprioritycompanycontactIdemaildomaininternalconnection
value reqstringpriority is "1" to "3"; internal is "true" or "false"; company and contactId are ids in your account; connection is an app name
modeenumdenied blocks the actionautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]Empty or All means every kind of send
createdAtstring
400Invalid match or limit reached
403Locked by a parent level, or caller may not edit this user
404No preferences for this user

Request

curl 'https://api.agnt.ai/users/<userId>/preferences/supervision/exceptions' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "match": {
    "kind": "domain",
    "value": "harborview.co"
  },
  "mode": "manual"
}'

Response

{
  "ok": true,
  "recipientException": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "label": "label",
    "match": {
      "kind": "domain",
      "value": "harborview.co"
    },
    "mode": "manual"
  }
}
DELETE/users/{userId}/preferences/supervision/exceptions/{exceptionId}

Delete a recipient exception

Deletes a recipient exception. Returns `204` with no body.

Path parameters

userId reqstring
exceptionId reqstring

Responses

204Deleted
404Exception not found
status reqinteger
error_codestring
error reqstring

Request

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