User

Get users

get

/v1/{organization}/user/

Retrieve all users in an organization.

Permissions

This endpoint is impacted by the following permissions:

Only users that the authenticated user has the User:GetUserInfo permission for are returned.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Query parameters

user_idstring[]Optional

The ID of the user.

Default: []

emailstring · email[]Optional

The email of the user.

Default: []

limitinteger · max: 100Optional

The maximum number of users to retrieve.

Default: 100

continuation_tokenintegerOptional

The token from the previous request to return the next page of users.

Default: 0

sort_bystring[]Optional

The fields to sort the sets by. Supported fields are first_name, last_name, email, user_stats.num_conversations, user_stats.num_messages, and user_stats.last_message_time. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 60 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/user/

GET /v1/{organization}/user/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "org_id": "text",
      "user_id": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "user_stats": {
        "num_conversations": 1,
        "num_messages": 1,
        "last_message_time": "2025-12-13T12:49:34.359Z"
      },
      "role": "text",
      "preferences": {
        "enable_response_recommendation": false,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true,
        "timezone": "text",
        "audio_keyterms": [
          "text"
        ]
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Create a new user

post

/v1/{organization}/user/

Invite a user to the Amigo platform. The endpoint will create a new user in the organization, linked to the supplied email address. The created user will remain in the unverified status and will not have access to most of Amigo's services.

If login_link is not-None, an email containing it will be sent to the user's email with descriptions indicating that this would allow the user to login and start their Amigo experience. Otherwise, no email will be sent.

Permissions

This endpoint requires the following permissions:

User:InviteUser on the user to invite.
The authenticated user must have greater privileges than the role assigned to the new user.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

first_namestring · min: 1Required

The first name of the user.

last_namestring · min: 1Required

The last name of the user.

emailstring · emailRequired

The email of the user. This email uniquely identifies the user in the organization.

login_linkany ofOptional

If specified, this link will be sent to the user's email as the link to start their Amigo experience. For Amigo's frontend, this would be the user's organization's login page with their email already filled in.

string · uri · min: 1 · max: 2083Optional

nullOptional

role_namestringRequired

The role to assign to the user. Only roles that are returned from the Get roles endpoint are allowed.

user_preferencesany ofOptional

If specified, the user's preferences will be set to this value instead of the organization default.

nullOptional

Responses

201

Succeeded

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or role is not found.

409

User with the same email already exists in this organization, or a related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/user/

POST /v1/{organization}/user/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 335

{
  "first_name": "text",
  "last_name": "text",
  "email": "[email protected]",
  "login_link": "https://example.com",
  "role_name": "text",
  "user_preferences": {
    "enable_response_recommendation": false,
    "preferred_language": "aaa",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true,
    "timezone": "Africa/Abidjan",
    "audio_keyterms": [
      "text"
    ]
  }
}

{
  "user_id": "text",
  "verify_link": "text"
}

Sign in with API key

post

/v1/{organization}/user/signin_with_api_key

Given an organization API key, issue an authorization token for the specified user. The token should then be attached to the Authorization header in subsequent Amigo API calls.

This is an alternative authorization method for users who cannot use the Amigo frontend to login and authenticate.

Authorizations

Path parameters

organizationstringRequired

Header parameters

x-api-keystringRequired

The value of the API key.

x-api-key-idstringRequired

The ID of the API key.

x-user-idstringRequired

The ID of the user to sign in as.

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

API key not found, is incorrect, or the requested user is not found.

404

Specified organization is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 5 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/user/signin_with_api_key

POST /v1/{organization}/user/signin_with_api_key HTTP/1.1
Host: api.amigo.ai
x-api-key: text
x-api-key-id: text
x-user-id: text
Accept: */*

{
  "id_token": "text",
  "expires_at": "2025-12-13T12:49:34.359Z"
}

post

/v1/{organization}/user/signin

Send a magic link to the user's email to sign in. If the specified email doesn't correspond to an user, the endpoint succeeds silently.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

redirect_linkstring · uri · min: 1Required

An Amigo platform link that the user gets redirected to after clicking the login link.

emailstring · emailRequired

Email of the user. This must correspond to an existing, verified user in the Amigo platform.

Responses

200

Succeeded.

application/json

Responseany

404

Specified organization is not found.

422

Invalid request path parameter or request body failed validation.

503

The service is going through temporary maintenance.

post

/v1/{organization}/user/signin

POST /v1/{organization}/user/signin HTTP/1.1
Host: api.amigo.ai
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "redirect_link": "https://example.com",
  "email": "[email protected]"
}

No content

Update user info

post

/v1/{organization}/user/{requested_user_id}

Update information about an user. Only fields that are specified in the request are updated.

Permissions

This endpoint requires the following permissions:

User:UpdateUserInfo for the user to update.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

requested_user_idstringRequired

The identifier of the user to update information for.

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

first_nameany ofOptional

The first name of the user to update. If null, the first name is not modified.

string · min: 1Optional

nullOptional

last_nameany ofOptional

The last name of the user to update. If null, the last name is not modified.

string · min: 1Optional

nullOptional

enable_response_recommendationany ofOptional

Whether to automatically recommend responses to the user if the user hasn't replied to the coach for a while. If null, the preference is not modified.

booleanOptional

nullOptional

preferred_languageany ofOptional

The preferred language for the user. The agent will attempt to converse to the user in this language if set. This field must be in the ISO 639-3 format. If null, erase the user's preferred setting, and the specific language used will be the agent's default spoken language. In order to not update this field, leave it out of the request or set it to an empty object (_NotSet).

Default: {}

string · enum · min: 3 · max: 3OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

nullOptional

timezoneany ofOptional

The user's timezone in the IANA tz database format. If not specified, the organization's timezone is used.

Default: {}

string · enum · min: 1OptionalPossible values:

object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

nullOptional

conversations_visible_to_adminsany ofOptional

Whether conversations are visible to the admins. If null, the preference is not modified.

booleanOptional

nullOptional

user_model_visible_to_adminsany ofOptional

Whether the user's user model is visible to the admins. If null, the preference is not modified.

booleanOptional

nullOptional

additional_contextany ofOptional

A list of additional context to update. If null, the context is not modified.

string[]Optional

nullOptional

audio_keytermsany ofOptional

A list of keyterms that are easy to get wrong during audio transcriptions that tend to occur commonly in audio sessions using this service. If null, the keyterms are not modified.

string[] · max: 20Optional

nullOptional

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/user/{requested_user_id}

POST /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 264

{
  "first_name": "text",
  "last_name": "text",
  "enable_response_recommendation": true,
  "preferred_language": "aaa",
  "timezone": "Africa/Abidjan",
  "conversations_visible_to_admins": true,
  "user_model_visible_to_admins": true,
  "additional_context": [
    "text"
  ],
  "audio_keyterms": [
    "text"
  ]
}

No content

Delete an user

delete

/v1/{organization}/user/{requested_user_id}

Delete an user. This endpoint deletes the user from the Amigo system.

Permissions

This endpoint requires the following permissions:

User.DeleteUser on the user to delete.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

requested_user_idstringRequired

The identifier of the user to delete.

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

409

A related operation is in progress.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 500 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

delete

/v1/{organization}/user/{requested_user_id}

DELETE /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

Get user model

get

/v1/{organization}/user/{user_id}/user_model

Retrieve the user models for an user.

Permissions

This endpoint requires the following permissions:

User:GetUserModel for the user to retrieve the user models for.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

user_idstringRequired

The ID of the user whose user models to retrieve.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 60 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/user/{user_id}/user_model

GET /v1/{organization}/user/{user_id}/user_model HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "user_models": [
    {
      "content": "text",
      "insight_ids": [
        "text"
      ],
      "dimensions": [
        {
          "description": "text",
          "tags": [
            "text"
          ]
        }
      ]
    }
  ],
  "additional_context": [
    "text"
  ]
}

Get memories

get

/v1/{organization}/user/{user_id}/memory

Retrieve memories for the specified users.

Permissions

This endpoint may be impacted by the following permissions:

Only memories with references that the authenticated user has the Conversation:GetMessage permission on will be returned.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

user_idstringRequired

The ID of the user to retrieve memories for.

Query parameters

idstring[]Optional

The IDs of the memories to retrieve.

Default: []

conversation_idstring[]Optional

The IDs of the conversations to retrieve memories from.

Default: []

limitinteger · max: 50Optional

The maximum number of memories to retrieve.

Default: 50

continuation_tokenintegerOptional

The token from the previous request to return the next page of memories.

Default: 0

sort_bystring[]Optional

The fields to sort the sets by. Supported fields are conversation_id and created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or user is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 40 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/user/{user_id}/memory

GET /v1/{organization}/user/{user_id}/memory HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "memories": [
    {
      "id": "text",
      "created_at": "2025-12-13T12:49:34.359Z",
      "conversation_id": "text",
      "references": [
        "text"
      ],
      "content": "text",
      "context": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Search users

get

/v1/{organization}/user/search/

Search users in the organization using their names or emails.

Permissions

This endpoint may be impacted by the following permissions:

Only users that the authenticated user has the User:GetUserInfo permission for will be returned.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Query parameters

querystringRequired

The search query. Any users whose name or email contains the query are returned.

user_idstring[]Optional

The IDs of the users.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 50 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/user/search/

GET /v1/{organization}/user/search/?query=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "org_id": "text",
      "user_id": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "user_stats": {
        "num_conversations": 1,
        "num_messages": 1,
        "last_message_time": "2025-12-13T12:49:34.359Z"
      },
      "role": "text",
      "preferences": {
        "enable_response_recommendation": false,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true,
        "timezone": "text",
        "audio_keyterms": [
          "text"
        ]
      }
    }
  ]
}

PreviousConversation NextRole

Last updated 1 hour ago

Was this helpful?

Good afternoon

Get users

Create a new user

Sign in with API key

Sign in with email

Update user info

Delete an user

Get user model

Get memories

Search users