LogoLogo
Go to website
  • Welcome
  • Getting Started
    • Amigo Overview
      • System Components
      • Overcoming LLM Limitations
      • [Advanced] Future-Ready Architecture
      • [Advanced] The Accelerating AI Landscape
    • The Journey with Amigo
      • Partnership Model
  • Concepts
    • Agent Core
      • Core Persona
      • Global Directives
    • Context Graphs
      • State-Based Architecture
      • [Advanced] Field Implementation Guidance
    • Functional Memory
      • Layered Architecture
      • User Model
      • [Advanced] Recall Mechanisms
      • [Advanced] Analytical Capabilities
    • Dynamic Behaviors
      • Side-Effect Architecture
      • Knowledge
      • [Advanced] Behavior Chaining
    • Evaluations
      • Testing Framework Examples
    • [Advanced] Reinforcement Learning
    • Safety
  • Glossary
  • Advanced Topics
    • Transition to Neuralese Systems
    • Agent V2 Architecture
  • Agent Building Best Practices
    • Dynamic Behaviors Guide
  • Developer Guide
    • Enterprise Integration Guide
      • Authentication
      • User Creation + Management
      • Service Discovery + Management
      • Conversation Creation + Management
      • Data Retrieval + User Model Management
      • Webhook Management
    • API Reference
      • V1/organization
      • V1/service
      • V1/conversation
      • V1/user
      • V1/role
      • V1/admin
      • V1/webhook_destination
      • V1/metric
      • V1/dynamic_behavior_set
      • V1/simulation
      • Models
Powered by GitBook
LogoLogo

Resources

  • Pricing
  • About Us

Company

  • Careers

Policies

  • Terms of Service

Amigo Inc. ©2025 All Rights Reserved.


On this page

Was this helpful?

Export as PDF
  1. Developer Guide
  2. API Reference

V1/user

PreviousV1/conversationNextV1/role

Was this helpful?

Sign in with API key

post

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-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
or
nullOptional
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
POST /v1/{organization}/user/signin_with_api_key HTTP/1.1
Host: api.amigo.ai
X-API-KEY: YOUR_API_KEY
Accept: */*
{
  "id_token": "text",
  "expires_at": "2025-05-10T02:04:28.287Z"
}

Get users

get

Retrieve all users in an organization.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

This endpoint is impacted by the following permissions:

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

Authorizations
Path parameters
organizationstringRequired
Query parameters
is_verifiedany ofOptional

Whether the user is verified.

booleanOptional
or
nullOptional
user_idany ofOptional

The ID of the user.

string[]Optional
or
nullOptional
emailany ofOptional

The email of the user,

string · email[]Optional
or
nullOptional
limitinteger · max: 600Optional

The maximum number of users to retrieve.

Default: 600
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 users by. Supported fields are first_name, last_name, email, user_stats.num_conversations, and user_stats.num_messages. 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
or
nullOptional
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
GET /v1/{organization}/user/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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-05-10T02:04:28.287Z"
      },
      "verified_at": "2025-05-10T02:04:28.287Z",
      "role": "text",
      "preferences": {
        "enable_response_recommendation": true,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Delete an user

delete

Delete an user. This endpoint deletes the user from the Amigo system, and also deletes all the user's information as much as possible.

  • If the user has created an API key, the user's data in Amigo's database are deleted, except for the User object, which is marked deleted. The Google user is deleted as well.

  • Otherwise the user is completely deleted. Their associated Google user is also deleted.

Permissions

This endpoint requires the following permissions:

  • User.GetUserInfo on the authenticated user.

  • User.DeleteUser on the user to delete.

Authorizations
Path parameters
organizationstringRequired
requested_user_idstringRequired

The identifier of the user to delete.

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
or
nullOptional
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 1000 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/user/{requested_user_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "not_deletable_reasons": [
    "There are API keys created by the user."
  ]
}

Get external events

get

Retrieve the external events for the specified user.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo on the authenticated user.

This endpoint may be impacted by the following permissions:

  • Only external events that the authenticated user has the User:GetExternalEvent permission on will be returned.

Authorizations
Path parameters
organizationstringRequired
user_idstringRequired

The ID of the user to retrieve external events for.

Query parameters
idany ofOptional

The IDs of the external events to retrieve.

string[]Optional
or
nullOptional
limitinteger · max: 20Optional

The maximum number of external events to retrieve.

Default: 20
continuation_tokenintegerOptional

The continuation token returned from the previous response to retrieve the next set of external events.

Default: 0
sort_bystring[]Optional

The field to sort the external events by. Supported fields are type, starts_at, and ends_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
or
nullOptional
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 40 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
get
GET /v1/{organization}/user/{user_id}/external_event HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "external_events": [
    {
      "_id": "text",
      "org_id": "text",
      "user_id": "text",
      "type": "text",
      "starts_at": "2025-05-10T02:04:28.287Z",
      "ends_at": "2025-05-10T02:04:28.287Z",
      "description": "text",
      "transcript": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Delete an external event

delete

Delete an external event.

Permissions

This endpoint requires the following permissions:

  • User.GetUserInfo for the authenticated user.

  • User.DeleteExternalEvent for this event.

Authorizations
Path parameters
organizationstringRequired
requested_user_idstringRequired

The identifier of the user to create this event for.

external_event_idstringRequired

The identifier of the external event to delete.

Pattern: ^[a-f0-9]{24}$
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
or
nullOptional
Responses
204
Successful Response
401
Invalid authorization credentials.
403
Missing required permissions.
404
Specified organization or event is not found.
422
Invalid request path parameter failed validation.
429
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/user/{requested_user_id}/external_event/{external_event_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

Get memories

get

Retrieve memories for the specified users.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo on the authenticated user.

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
Path parameters
organizationstringRequired
user_idstringRequired

The ID of the user to retrieve memories for.

Query parameters
idany ofOptional

The IDs of the memories to retrieve.

string[]Optional
or
nullOptional
conversation_idany ofOptional

The IDs of the conversations to retrieve memories from.

string[]Optional
or
nullOptional
limitinteger · max: 50Optional

The maximum number of memories to retrieve.

Default: 50
continuation_tokenintegerOptional

The continuation token returned from the previous response to retrieve the next set of memories.

Default: 0
sort_bystring[]Optional

The field to sort the memories by. Supported fields are conversation_id and timestamp. 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
or
nullOptional
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
GET /v1/{organization}/user/{user_id}/memory HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "memories": [
    {
      "id": "text",
      "timestamp": "2025-05-10T02:04:28.287Z",
      "conversation_id": "text",
      "references": [
        "text"
      ],
      "content": "text",
      "context": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Search users

get

Search users in the organization using their names or emails.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

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
Path parameters
organizationstringRequired
Query parameters
querystringRequired

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

is_verifiedany ofOptional

Whether the user is verified.

booleanOptional
or
nullOptional
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
or
nullOptional
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
GET /v1/{organization}/user/search/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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-05-10T02:04:28.287Z"
      },
      "verified_at": "2025-05-10T02:04:28.287Z",
      "role": "text",
      "preferences": {
        "enable_response_recommendation": true,
        "preferred_language": "text",
        "conversations_visible_to_admins": true,
        "user_model_visible_to_admins": true
      }
    }
  ]
}
  • POSTUpdate user info
  • GETGet user model
  • POSTSign in with email
  • POSTSign in with API key
  • GETGet users
  • POSTCreate a new user
  • POSTVerify a user
  • DELETEDelete an user
  • GETGet external events
  • POSTCreate an external event
  • DELETEDelete an external event
  • GETGet memories
  • GETSearch users

Get user model

get

Retrieve the user models for an user.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

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

Authorizations
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
or
nullOptional
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
GET /v1/{organization}/user/{user_id}/user_model HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "user_models": [
    {
      "content": "text",
      "insight_ids": [
        "text"
      ],
      "dimensions": [
        {
          "description": "text",
          "tags": [
            "text"
          ]
        }
      ]
    }
  ],
  "additional_context": [
    "text"
  ]
}

Update user info

post

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

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

  • User:UpdateUserInfo for the user to update.

Authorizations
Path parameters
organizationstringRequired
requested_user_idstringRequired

The identifier of the user to update information for.

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
or
nullOptional
Body
first_nameany ofOptional

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

string · min: 1Optional
or
nullOptional
last_nameany ofOptional

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

string · min: 1Optional
or
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
or
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-1 alpha-2 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: {}
stringOptionalPattern: ^\w{2}$
or
object · _NotSetOptional

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

or
nullOptional
conversations_visible_to_adminsany ofOptional

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

booleanOptional
or
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
or
nullOptional
additional_contextany ofOptional

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

string[]Optional
or
nullOptional
Responses
204
Succeeded.
401
Invalid authorization credentials.
403
Missing required permissions.
404
Specified organization or user is not found.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/user/{requested_user_id}/user HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 211

{
  "first_name": "text",
  "last_name": "text",
  "enable_response_recommendation": true,
  "preferred_language": "text",
  "conversations_visible_to_admins": true,
  "user_model_visible_to_admins": true,
  "additional_context": [
    "text"
  ]
}

No content

Sign in with email

post

Send a magic link to the user's email to sign in.

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
or
nullOptional
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
404
Specified organization or user is not found.
422
Invalid request path parameter or request body failed validation.
429
The IP has exceeded the rate limit of 5 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
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": "name@gmail.com"
}
{
  "user_id": "text"
}

Create a new user

post

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.GetUserInfo for the authenticated user.

  • User.InviteUser on the user to invite.

  • The authenticated user must have greater privileges than the role assigned to the new user.

Authorizations
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
or
nullOptional
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
or
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.

or
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.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 1000 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/user/invite HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "first_name": "text",
  "last_name": "text",
  "email": "name@gmail.com",
  "login_link": "https://example.com",
  "role_name": "text",
  "user_preferences": {
    "enable_response_recommendation": true,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true
  }
}
{
  "user_id": "text",
  "verify_link": "text"
}

Verify a user

post

Mark the user as verified. It's not permitted to use the Amigo platform with an unverified user account.

Permissions:

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

This endpoint may require the following permissions:

  • User.UpdateUserInfo for the requested user if any field in Request is not None.

Authorizations
Path parameters
organizationstringRequired
requested_user_idstringRequired

The identifier of the user to verify.

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
or
nullOptional
Body
first_nameany ofOptional

The first name of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

string · min: 1Optional
or
nullOptional
last_nameany ofOptional

The last name of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

string · min: 1Optional
or
nullOptional
user_preferencesany ofOptional

The preferences of the user, if the user has a different preference than what's already indicated during invitation. Only updated if specified.

or
nullOptional
Responses
204
Succeeded.
401
Invalid authorization credentials.
403
Missing required permissions.
404
Specified organization or user is not found.
409
The user is already verified.
422
Invalid request path parameter or request body failed validation.
429
The IP has exceeded the rate limit of 1000 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/user/{requested_user_id}/verify HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 202

{
  "first_name": "text",
  "last_name": "text",
  "user_preferences": {
    "enable_response_recommendation": true,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true
  }
}

No content

Create an external event

post

Create an external event.

Permissions

This endpoint requires the following permissions:

  • User.GetUserInfo for the authenticated user.

  • User.CreateExternalEvent for this event.

Authorizations
Path parameters
organizationstringRequired
requested_user_idstringRequired

The identifier of the user to create this event for.

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
or
nullOptional
Body
typestring · min: 1Required

The type of this event.

starts_atstring · date-timeRequired

The time when this event started in UTC.

ends_atstring · date-timeRequired

The time whent this event ended in UTC.

descriptionstring · min: 1Required

A description of this event.

transcriptstring · min: 1Required

The transcript of this event.

Responses
201
Succeeded.
application/json
400
The event description or transcript failed validation.
401
Invalid authorization credentials.
403
Missing required permissions.
404
Specified organization is not found.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/user/{requested_user_id}/external_event HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "type": "text",
  "starts_at": "2025-05-10T02:04:28.287Z",
  "ends_at": "2025-05-10T02:04:28.287Z",
  "description": "text",
  "transcript": "text"
}
{
  "external_event_id": "text"
}