Amigo User API

openapi: 3.2.0
info:
  title: Amigo Account User API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: User
paths:
  /v1/{organization}/user/:
    post:
      tags:
      - User
      summary: Create a new user
      description: '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.'
      operationId: create-invited-user
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__user__create_invited_user__Request'
      responses:
        '201':
          description: Succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__create_invited_user__Response'
        '409':
          description: User with the same email already exists in this organization, or a related operation is in progress.
        '404':
          description: Specified organization or role is not found.
        '422':
          description: Invalid request path parameter or request body failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
    get:
      tags:
      - User
      summary: Get users
      description: '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.'
      operationId: get-users
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: user_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
          description: The ID of the user.
          default: []
          title: User Id
        description: The ID of the user.
      - name: email
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            format: email
          description: The email of the user.
          default: []
          title: Email
        description: The email of the user.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 0
          description: The maximum number of users to retrieve.
          default: 100
          title: Limit
        description: The maximum number of users to retrieve.
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          description: The token from the previous request to return the next page of users.
          default: 0
          title: Continuation Token
        description: The token from the previous request to return the next page of users.
      - name: sort_by
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: 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: []
          title: Sort By
        description: 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.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__get_users__Response'
        '404':
          description: Specified organization is not found.
        '422':
          description: Invalid request path parameter or request query parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 60 requests per minute for this endpoint.
  /v1/{organization}/user/signin_with_api_key:
    post:
      tags:
      - User
      summary: Sign in with API key
      description: '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.'
      operationId: sign-in-with-api-key
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
          description: The value of the API key.
          title: X-Api-Key
        description: The value of the API key.
      - name: x-api-key-id
        in: header
        required: true
        schema:
          type: string
          description: The ID of the API key.
          title: X-Api-Key-Id
        description: The ID of the API key.
      - name: x-user-id
        in: header
        required: true
        schema:
          type: string
          description: The ID of the user to sign in as.
          title: X-User-Id
        description: The ID of the user to sign in as.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__sign_in_with_api_key__Response'
        '404':
          description: Specified organization is not found.
        '401':
          description: API key not found, is incorrect, or the requested user is not found.
        '422':
          description: Invalid request path parameter failed validation.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 5 requests per minute for this endpoint.
      security:
      - API-Key-Authorization-Key: []
        API-Key-Authorization-ID: []
        API-Key-Authorization-UserID: []
  /v1/{organization}/user/signin:
    post:
      tags:
      - User
      summary: Sign in with email
      description: 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.
      operationId: sign-in-with-email
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__user__sign_in_with_email__Request'
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema: {}
        '404':
          description: Specified organization is not found.
        '422':
          description: Invalid request path parameter or request body failed validation.
        '503':
          description: The service is going through temporary maintenance.
      security: []
  /v1/{organization}/user/{requested_user_id}:
    post:
      tags:
      - User
      summary: Update user info
      description: '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.'
      operationId: update-user-info
      parameters:
      - name: requested_user_id
        in: path
        required: true
        schema:
          type: string
          description: The identifier of the user to update information for.
          title: Requested User Id
        description: The identifier of the user to update information for.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__user__update_user_info__Request'
      responses:
        '204':
          description: Succeeded.
        '422':
          description: Invalid request path parameter or request body failed validation.
        '404':
          description: Specified organization or user is not found.
        '409':
          description: A related operation is in progress.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
    delete:
      tags:
      - User
      summary: Delete an user
      description: '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.'
      operationId: delete-user
      parameters:
      - name: requested_user_id
        in: path
        required: true
        schema:
          type: string
          description: The identifier of the user to delete.
          title: Requested User Id
        description: The identifier of the user to delete.
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '204':
          description: Succeeded.
        '404':
          description: Specified organization or user is not found.
        '400':
          description: The user is currently active in Actions development.
        '422':
          description: Invalid request path parameter failed validation.
        '409':
          description: A related operation is in progress.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 500 requests per minute for this endpoint.
  /v1/{organization}/user/{user_id}/user_model:
    get:
      tags:
      - User
      summary: Get user model
      description: '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.'
      operationId: get-user-model
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          description: The ID of the user whose user models to retrieve.
          title: User Id
        description: The ID of the user whose user models to retrieve.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__get_user_model__Response'
        '404':
          description: Specified organization or user is not found.
        '422':
          description: Invalid request path parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 60 requests per minute for this endpoint.
  /v1/{organization}/user/{user_id}/memory:
    get:
      tags:
      - User
      summary: Get memories
      description: '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.'
      operationId: get-memories
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          description: The ID of the user to retrieve memories for.
          title: User Id
        description: The ID of the user to retrieve memories for.
      - name: id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The IDs of the memories to retrieve.
          default: []
          title: Id
        description: The IDs of the memories to retrieve.
      - name: conversation_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^[a-f0-9]{24}$
          description: The IDs of the conversations to retrieve memories from.
          default: []
          title: Conversation Id
        description: The IDs of the conversations to retrieve memories from.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 0
          description: The maximum number of memories to retrieve.
          default: 50
          title: Limit
        description: The maximum number of memories to retrieve.
      - name: continuation_token
        in: query
        required: false
        schema:
          type: integer
          description: The token from the previous request to return the next page of memories.
          default: 0
          title: Continuation Token
        description: The token from the previous request to return the next page of memories.
      - name: sort_by
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: 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: []
          title: Sort By
        description: 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.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__get_memories__Response'
        '404':
          description: Specified organization or user is not found.
        '422':
          description: Invalid request path parameter or request query parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 40 requests per minute for this endpoint.
  /v1/{organization}/user/search/:
    get:
      tags:
      - User
      summary: Search users
      description: '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.'
      operationId: search-users
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: query
        in: query
        required: true
        schema:
          type: string
          description: The search query. Any users whose name or email contains the query are returned.
          title: Query
        description: The search query. Any users whose name or email contains the query are returned.
      - name: user_id
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
          description: The IDs of the users.
          default: []
          title: User Id
        description: The IDs of the users.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      responses:
        '200':
          description: Succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__app__endpoints__user__search_users__Response'
        '404':
          description: Specified organization is not found.
        '422':
          description: Invalid request path parameter or request query parameter failed validation.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
  /v1/{organization}/user/{requested_user_id}/variable:
    post:
      tags:
      - User
      summary: Modify the variables of an user
      description: 'Upsert or delete the user''s variables. These changes are only reflected in tool invocations that are not yet made.


        #### Permissions

        This endpoint requires the following permissions:

        * `User:UpdateUserInfo` for the user to modify variables for.'
      operationId: modify-user-variables
      parameters:
      - name: organization
        in: path
        required: true
        schema:
          type: string
          title: Organization
      - name: requested_user_id
        in: path
        required: true
        schema:
          type: string
          description: The identifier of the user to update information for.
          title: Requested User Id
        description: The identifier of the user to update information for.
      - name: x-mongo-cluster-name
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: X-Mongo-Cluster-Name
        description: 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.
      - name: Sec-WebSocket-Protocol
        in: header
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
          title: Sec-Websocket-Protocol
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__app__endpoints__user__modify_user_variables__Request'
      responses:
        '204':
          description: Succeeded.
        '422':
          description: Invalid request path parameter or request body failed validation.
        '404':
          description: Specified organization or user is not found.
        '400':
          description: One or more variables to delete do not exist, or the user has exceeded the limit of 20 nonsensitive variables.
        '401':
          description: Invalid authorization credentials.
        '403':
          description: Missing required permissions.
        '503':
          description: The service is going through temporary maintenance.
        '429':
          description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
components:
  schemas:
    src__app__endpoints__user__get_user_model__Response:
      properties:
        user_models:
          items:
            $ref: '#/components/schemas/UserModel'
          type: array
          title: User Models
          description: The latest user models for the user.
        additional_context:
          items:
            type: string
          type: array
          title: Additional Context
          description: The additional context for the user.
      type: object
      required:
      - user_models
      - additional_context
      title: Response
    src__app__endpoints__user__create_invited_user__Request:
      properties:
        first_name:
          $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1'
          description: The first name of the user.
        last_name:
          $ref: '#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1'
          description: The last name of the user.
        email:
          type: string
          format: email
          title: Email
          description: The email of the user. This email uniquely identifies the user in the organization.
        login_link:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Login Link
          description: '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.'
        role_name:
          type: string
          title: Role Name
          description: The role to assign to the user. Only roles that are returned from the [Get roles](get-roles) endpoint are allowed.
        nonsensitive_user_variables:
          additionalProperties:
            type: string
          propertyNames:
            $ref: '#/components/schemas/StrippedNonemptyString_a-z___a-z0-9___lambda__at_0xffff718d0a90__'
          type: object
          maxProperties: 19
          title: Nonsensitive User Variables
          description: The nonsensitive user variables to provide to the tool during invocation.
          default: {}
        sensitive_user_variables:
          additionalProperties:
            type: string
          propertyNames:
            $ref: '#/components/schemas/StrippedNonemptyString_a-z___a-z0-9_______'
          type: object
          maxProperties: 20
          title: Sensitive User Variables
          description: The sensitive user variables to provide to the tool during invocation.
          default: {}
        user_preferences:
          anyOf:
          - $ref: '#/components/schemas/src__app__endpoints__user__create_invited_user__Request__Preferences'
          - type: 'null'
          description: If specified, the user's preferences will be set to this valu

# --- truncated at 32 KB (363 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-user-api-openapi.yml