V1/organization
Was this helpful?
Was this helpful?
Return a list of agents for the organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
This endpoint may be impacted by the following permissions:
Only agents that the authenticated user has the Organization:GetAgent
permission on will be returned.
Whether the agent is deprecated.
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.
Delete the specified agent from the organization. In practice, this endpoint marks the agent as deprecated, but will not delete this agent nor any of its versions. It does prevent new services (or inactive services to be activated) from using this agent.
An error will be raised if this endpoint is called when an active service still utilizes this agent. However, any ongoing conversation using this agent will continue to work.
Permissions:
User:GetUserInfo
for the authenticated user.
Organization:DeleteAgent
for the agent to delete.
The ID of the agent to delete
^[a-f0-9]{24}$
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.
No content
Return a list of service hierarchical state machines for the organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
This endpoint may be impacted by the following permissions:
Only state machines that the authenticated user has the Organization:GetServiceHierarchicalStateMachine
permission on will be returned.
Whether the state machine is deprecated.
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.
No content
Delete the specified state machine from the organization. In practice, this endpoint marks the state machine as deprecated, but will not delete this state machine nor any of its versions. It does prevent new services (or inactive services to be activated) from using this state machine.
An error will be raised if this endpoint is called when an active service still utilizes this state machine. However, any ongoing conversation using this state machine, as well as any state machine version that depends on this state machine will continue to work.
Permissions:
User:GetUserInfo
for the authenticated user.
Organization:DeleteServiceHierarchicalStateMachine
for the state machine to delete.
The ID of the state machine to delete
^[a-f0-9]{24}$
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.
No content
Get all API keys for the organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
This endpoint is impacted by the following permissions:
Only API keys that the authenticated user has the Organization:GetAPIKey
permission for are returned.
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.
Delete the given API key from this organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:DeleteAPIKey
.
ID of the API key to delete.
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.
Retrieve the versions of an agent.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetAgent
for the agent to retrieve.
This endpoint may be impacted by the following permissions:
Most fields involved in the inner workings of the agent are only populated if the authenticated user has the Organization:GetAgentDetails
permission on the agent.
The ID of the agent.
^[a-f0-9]{24}$
The versions of the agent to retrieve. One can specify an exact version to retrieve, which is either the version number or latest
, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -
, and every version within the range would be retrieved.
1
The maximum number of agent versions to return.
10
The continuation token from the previous request used to retrieve the next page of agent version.
0
The fields to sort the versions by. Supported fields are version
. Specify a +
before the field name to indicate ascending sorting and -
for descending sorting. Multiple fields can be specified to break ties.
[]
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.
Retrieve the versions of a state machine.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetServiceHierarchicalStateMachine
for the state machine to retrieve.
This endpoint may require the following permissions:
Many details about the state machine are only populated if the authenticated user has the Organization:GetServiceHierarchicalStateMachineDetails
permission for the state machine to retrieve.
The ID of the state machine.
^[a-f0-9]{24}$
The versions of the state machine to retrieve. One can specify an exact version to retrieve, which is either the version number or latest
, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -
, and every version within the range would be retrieved.
1
The maximum number of state machine versions to return.
10
The continuation token from the previous request used to retrieve the next page of state machine versions.
0
The fields to sort the versions by. Supported fields are version
. Specify a +
before the field name to indicate ascending sorting and -
for descending sorting. Multiple fields can be specified to break ties.
[]
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.
Get the list of user dimensions for the organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetOrganizationDetails
for the current organization.
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.
Get the details of an organization.
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.
Modify elements of an organization.
Permissions
This endpoint requries the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:ModifyOrganization
to modify the organization.
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.
An advertising tagline for the services offered by this organization. If null
, this field is not updated.
A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization. If null
, this field is not updated.
Additional descriptions of the services offered by this organization that is displayed below main_description
in a smaller font. If null
, this field is not updated.
A logo for the organization that will be displayed on the Amigo frontend for this organization, as well as all Amigo communications to users on behalf of the organization. Must be provided as base64 encoded bytes of a PNG image of aspect ratio 5:2 with minimum size 400 * 160 pixels. Only updated if not null.
A square logo of the organization. Must be provided as base64 encoded bytes of a square PNG image of size at least 40 * 40 pixels. Only updated if not null.
Favicon for the Amigo frontend for this organization. Must be provided as base64 encoded bytes of a square ICO image that's of size at least 40 * 40 pixels. Only updated if not null.
An optional image of the main persona of the organization that is displayed on the signup page for this organization in base64 encoded bytes of a PNG image of size at least 292 * 400 pixels and aspect ratio
0.73. If null
, a default headshot is used. If not set or equal to an empty object, it's not updated.
{}
A specific type to indicate that a field is not set in the request.
User dimensions for the organization. If not set or null
, this field is not updated.
The default user preferences for the organization. If null
, this field is not updated.
A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow. If null
, this field is not updated.
No content
Set up a new organization in the Amigo system. Specifically, it
creates a new organization within the Amigo Mongo database with the given details.
Along with the new organization, 5 default roles are created:
DefaultUserRole
.
DefaultAdministratorRole
.
DefaultAmigoAdministratorRole
.
DefaultSuperAdministratorRole
.
A super user, admin@amigo.ai
, is created and granted the DefaultSuperAdministratorRole
.
creates a new tenant in Google Identity Platform for users in this organization.
creates a new Route53 record, {org_id}.amigo.ai
, that hosts the Amigo frontend for this organization.
creates a new domain, {org_id}.amigo.ai
, on Vercel.
The x-mongo-cluster-name
header is mandatory for this endpoint.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:CreateOrganization
. for the organization to create.
Role:CreateRole
for the default roles to create for each organization.
User.InviteUser
for admin@amigo.ai
.
The authenticated user must have greater or equal privileges than DefaultSuperAdministratorRole
, which effectively means
it must take the DefaultSuperAdministratorRole
as well.
The Mongo cluster name to perform this request in.
A human friendly name of the organization.
An advertising tagline for the services offered by this organization.
A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization.
Additional descriptions of the services offered by this organization that is displayed below main_description
in a smaller font.
A logo for the organization that will be displayed on the Amigo frontend for this organization, as well as all Amigo communications to users on behalf of the organization. Must be provided as base64 encoded bytes of a PNG image of aspect ratio 5:2 with minimum size 400 * 160 pixels.
A square logo of the organization. Must be provided as base64 encoded bytes of a square PNG image of size at least 40 * 40 pixels.
Favicon for the Amigo frontend for this organization. Must be provided as base64 encoded bytes of a square ICO image that's of size at least 40 * 40 pixels.
An optional image of the main persona of the organization that is displayed on the signup page for this organization in base64 encoded bytes of a PNG image of size at least 292 * 400 pixels and aspect ratio 0.73. If not specified, a default headshot is used.
A list of markdown text that's displayed during the onboarding flow of this organization. Each entry corresponds to a page in the onboarding flow.
Create a new agent for the given organization. No default version for the agent will be created, so one must later to create a version for this agent so it can be used in a service.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:CreateAgent
for the new agent.
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.
The name of the new agent.
Create a new version of the given agent. If there's no existing versions, all fields in the request must be filled and they will be used to create the initial version of the agent. Otherwise, only fill the fields that need to be updated, and the new version will retain other fields from the previous latest version.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetAgent
for the agent to create a new version for.
Organization:CreateAgentVersion
for the new version of the agent.
The ID of the agent to create a new version for.
^[a-f0-9]{24}$
The version number of the new agent version. If specified, this endpoint throws an error if the next version of the agent in the database doesn't equal to the value of this parameter.
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.
The agent's initials.
The agent's profile picture as base64 encoded PNG bytes. The picture must be square and at least 300 * 300 pixels.
Information about the agent's identity.
A description of the agent's background.
A list of behavioral guidelines that this agent follows.
A list of descriptions that illustrate the communication styles of this agent.
The Elevenlabs voice config for the agent. If set to null, the default setting is used. If not set or set to an empty object, the setting on the existing version is used.
{}
A specific type to indicate that a field is not set in the request.
Create a new state machine for the given organization. No default version for the state machine will be created, so one must later create a version for this state machine so it can be used in a service.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:CreateServiceHierarchicalStateMachine
for the new service hierarchical state machine.
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.
The name of the new state machine.
Create a new version for the given service hierarchical state machine. The new version will be created with the supplied data. It needs to satisfy the following constraints:
Each action state must have at least one action.
For action and decision states, each exit condition's next_state
must either be a string that exists in the states and cannot be the same as the current state, or a 2-tuple of strings,
with the first string of the form {external_service_hierarchical_state_machine_reference.external_state_name}
, and the second string the jumpback state which must be a state
in the states.
For recall states, next_state
must either be a string that exists in the states and cannot be the same as the current state, or a 2-tuple of strings,
with the first string of the form {external_service_hierarchical_state_machine_reference.external_state_name}
, and the second string the jumpback state which must be a state
in the states.
The terminal state cannot have exit conditions and must have exactly one action.
See the per-request-field documentation for more field-specific constraints.
Permissions:
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetServiceHierarchicalStateMachine
for the service hierarchical state machine to create a new version for.
Organization:CreateServiceHierarchicalStateMachineVersion
for the service hierarchical state machine.
The ID of the service hierarchical state machine to create a new version for.
^[a-f0-9]{24}$
The version number of the new state machine version. If specified, this endpoint throws an error if the next version of the state machine in the database doesn't equal to the value of this parameter.
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.
A description of the service hierarchical state machine.
The state a new user will be in when a session starts. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$
The state a returning user will be in when a session starts. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$
The state the user will be in when the session ends. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$
A list of guidelines for how the agent will navigate between subgoals and exit conditions within this state. This is injected into the intra_state_navigation_guidelines
field of every action state.
A list of guidelines for how the agent will behave when engaging with user. This is injected into the action_guidelines
field of every action state.
A list of guidelines for how the agent will not behave when engaging with user. This is injected into the boundary_constraints
field of every action state.
Create a new API key for the given organization. This API key authorizes the organization to retrieve a per-user access token for users in this organization which allows the users to access most of Amigo's API endpoints. This API key is valid for the duration specified in the request. There's no way to extend the duration of an API key. The API key is not retrievable after issuance, so please keep it in a secure location.
Each organization has a maximum limit of 20 API keys.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:CreateAPIKey
.
This endpoint requires the authenticated user to have more privileges than the role associated with the API key.
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.
The valid duration of the API key. Should be supplied in the ISO8601 format. Must be between 1 to 90 days.
The name of the role associated with the key. When using this API key to authenticate, it can only authenticate for users with roles that are less permissive than this role.
DefaultAdministratorRole
Compute metrics for an organization.
Permissions
This endpoint requires the following permissions:
User:GetUserInfo
for the authenticated user.
Organization:GetMetric
for the organization.
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.