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/organization

PreviousAPI ReferenceNextV1/service

Was this helpful?

Get agents for an organization

get

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.

Authorizations
Path parameters
organizationstringRequired
Query parameters
deprecatedany ofOptional

Whether the agent is deprecated.

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
The specified organization does not exist.
422
Invalid request path parameter or query parameter failed validation.
429
The source IP address 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}/organization/agent HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "agents": [
    {
      "id": "text",
      "name": "text",
      "deprecated": true,
      "latest_version": 1
    }
  ]
}

Delete an agent

delete

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.

Authorizations
Path parameters
agent_idstringRequired

The ID of the agent to delete

Pattern: ^[a-f0-9]{24}$
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
Responseany
400
An active service exists that utilizes this agent.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or agent does not exist.
409
The specified agent is already deleted
422
Invalid request path parameter failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/organization/agent/{agent_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

Get service hierarchical state machines for an organization

get

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.

Authorizations
Path parameters
organizationstringRequired
Query parameters
deprecatedany ofOptional

Whether the state machine is deprecated.

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
Responseany
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization does not exist.
422
Invalid request path parameter or query parameter failed validation.
429
The source IP address 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}/organization/service_hierarchical_state_machine HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

Delete a service hierarchical state machine

delete

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.

Authorizations
Path parameters
state_machine_idstringRequired

The ID of the state machine to delete

Pattern: ^[a-f0-9]{24}$
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
Responseany
400
An active service exists that utilizes this state machine.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or state machine does not exist.
409
The specified state machine is already deleted
422
Invalid request path parameter failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/organization/service_hierarchical_state_machine/{state_machine_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

Get API keys for the organization

get

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.

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
Invalid authorization credentials.
403
Missing required permissions.
404
The organization does not exist.
422
Invalid request path 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}/organization/api_key/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "api_keys": [
    {
      "_id": "text",
      "org_id": "text",
      "key_id": "text",
      "expires_at": "2025-05-10T09:03:54.240Z",
      "hashed_value": "text",
      "creator": {
        "user_id": "text",
        "org_id": "text"
      },
      "role_id": "text"
    }
  ]
}

Delete an API key

delete

Delete the given API key from this organization.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

  • Organization:DeleteAPIKey.

Authorizations
Path parameters
organizationstringRequired
api_key_idstringRequired

ID of the API key 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
The specified organization or the API key does not exist.
422
Invalid request path parameter failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/organization/api_key/{api_key_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "deleted_key_id": "text"
}

Get agent versions

get

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.

Authorizations
Path parameters
agent_idstringRequired

The ID of the agent.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Query parameters
versionany ofOptional

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.

Example: 1
stringOptional
or
nullOptional
limitinteger · min: 1 · max: 10Optional

The maximum number of agent versions to return.

Default: 10
continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of agent version.

Default: 0
sort_bystring[]Optional

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.

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 agent is not found.
422
Invalid request path parameter or request query parameter failed validation.
429
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
get
GET /v1/{organization}/organization/agent/{agent_id}/version HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "agent_versions": [
    {
      "id": "text",
      "org_id": "text",
      "agent_id": "text",
      "version": 1,
      "initials": "text",
      "pfp": "text",
      "identity_name": "text",
      "created_at": "2025-05-10T09:03:54.240Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Get service hierarchical state machine versions

get

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.

Authorizations
Path parameters
service_hierarchical_state_machine_idstringRequired

The ID of the state machine.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Query parameters
versionany ofOptional

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.

Example: 1
stringOptional
or
nullOptional
limitinteger · min: 1 · max: 10Optional

The maximum number of state machine versions to return.

Default: 10
continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of state machine versions.

Default: 0
sort_bystring[]Optional

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.

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 service hierarchical state machine is not found.
422
Invalid request path parameter or request query parameter failed validation.
429
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
get
GET /v1/{organization}/organization/service_hierarchical_state_machine/{service_hierarchical_state_machine_id}/version HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "state_machine_versions": [
    {
      "id": "text",
      "org_id": "text",
      "service_hierarchical_state_machine_id": "text",
      "version": 1,
      "created_at": "2025-05-10T09:03:54.240Z",
      "description": "text",
      "states": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "text",
          "objective": "text",
          "actions": [
            "text"
          ],
          "intra_state_navigation_guidelines": [
            "text"
          ],
          "action_guidelines": [
            "text"
          ],
          "boundary_constraints": [
            "text"
          ],
          "exit_conditions": [
            {
              "description": "text",
              "next_state": "text"
            }
          ],
          "message_metadata": [
            "text"
          ]
        }
      },
      "new_user_initial_state": "text",
      "returning_user_initial_state": "text",
      "terminal_state": "text",
      "references": {
        "ANY_ADDITIONAL_PROPERTY": []
      },
      "global_intra_state_navigation_guidelines": [
        "text"
      ],
      "global_action_guidelines": [
        "text"
      ],
      "global_boundary_constraints": [
        "text"
      ]
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Get user dimensions for the organization

get

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.

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
Invalid authorization credentials.
403
Missing required permissions.
404
The organization does not exist.
422
Invalid request path 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}/organization/user_dimensions/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ]
}
  • GETGet an organization
  • POSTModify an organization
  • PUTCreate an organization
  • GETGet agents for an organization
  • POSTCreate an agent
  • POSTCreate an agent version
  • DELETEDelete an agent
  • GETGet service hierarchical state machines for an organization
  • POSTCreate a service hierarchical state machine
  • POSTCreate a service hierarchical state machine version
  • DELETEDelete a service hierarchical state machine
  • GETGet API keys for the organization
  • POSTCreate an API key
  • DELETEDelete an API key
  • GETGet agent versions
  • GETGet service hierarchical state machine versions
  • POSTGet metrics for an organization
  • GETGet user dimensions for the organization

Get an organization

get

Get the details of an organization.

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
404
The specified organization does not exist.
422
Invalid request path parameter failed validation.
429
The source IP address has exceeded the rate limit of 100 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
get
GET /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Accept: */*
{
  "org_id": "text",
  "org_name": "text",
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "text",
  "onboarding_instructions": [
    "text"
  ]
}

Modify an organization

post

Modify elements of an organization.

Permissions

This endpoint requries the following permissions:

  • User:GetUserInfo for the authenticated user.

  • Organization:ModifyOrganization to modify the organization.

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
titleany ofOptional

An advertising tagline for the services offered by this organization. If null, this field is not updated.

string · min: 1Optional
or
nullOptional
main_descriptionany ofOptional

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.

string · min: 1Optional
or
nullOptional
sub_descriptionany ofOptional

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.

string · min: 1Optional
or
nullOptional
logoany ofOptional

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.

string · base64Optional
or
nullOptional
square_logoany ofOptional

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.

string · base64Optional
or
nullOptional
faviconany ofOptional

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.

string · base64Optional
or
nullOptional
signup_page_headshotany ofOptional

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.

Default: {}
string · base64Optional
or
object · _NotSetOptional

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

or
nullOptional
user_dimensionsany ofOptional

User dimensions for the organization. If not set or null, this field is not updated.

or
nullOptional
default_user_preferencesany ofOptional

The default user preferences for the organization. If null, this field is not updated.

or
nullOptional
onboarding_instructionsany ofOptional

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.

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

{
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "default_user_preferences": {
    "enable_response_recommendation": true,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true
  },
  "onboarding_instructions": [
    "text"
  ]
}

No content

Create an organization

put

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.

Authorizations
Path parameters
organizationstringRequired
Header parameters
x-mongo-cluster-namestringRequired

The Mongo cluster name to perform this request in.

Body
org_namestring · min: 1Required

A human friendly name of the organization.

titlestring · min: 1Required

An advertising tagline for the services offered by this organization.

main_descriptionstring · min: 1Required

A description of the services offered by this organization that is displayed on the login page for the Amigo frontend for this organization.

sub_descriptionstring · min: 1Required

Additional descriptions of the services offered by this organization that is displayed below main_description in a smaller font.

logostring · base64Required

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.

square_logostring · base64Required

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.

faviconstring · base64Required

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.

signup_page_headshotany ofRequired

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.

string · base64Optional
or
nullOptional
onboarding_instructionsstring[]Required

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.

Responses
201
Succeeded.
application/json
401
Invalid authorization credentials.
403
Missing required permissions.
409
Conflicts with existing organization with the same `org_id`.
422
Invalid request path parameter or request body 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.
put
PUT /v1/{organization}/organization/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
x-mongo-cluster-name: text
Content-Type: application/json
Accept: */*
Content-Length: 431

{
  "org_name": "text",
  "title": "text",
  "main_description": "text",
  "sub_description": "text",
  "user_dimensions": [
    {
      "description": "text",
      "tags": [
        "text"
      ]
    }
  ],
  "logo": "text",
  "square_logo": "text",
  "favicon": "text",
  "signup_page_headshot": "text",
  "default_user_preferences": {
    "enable_response_recommendation": true,
    "preferred_language": "text",
    "conversations_visible_to_admins": true,
    "user_model_visible_to_admins": true
  },
  "onboarding_instructions": [
    "text"
  ]
}
{
  "org_id": "text"
}

Create an agent

post

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.

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
agent_namestring · min: 1 · max: 256Required

The name of the new agent.

Responses
201
Succeeded.
application/json
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization does not exist.
409
An `Agent` with the same name already exists.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/organization/agent HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "agent_name": "text"
}
{
  "id": "text"
}

Create an agent version

post

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.

Authorizations
Path parameters
agent_idstringRequired

The ID of the agent to create a new version for.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Query parameters
versionany ofOptional

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.

integer · min: 1Optional
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
Body
initialsany ofOptional

The agent's initials.

string · min: 1 · max: 3Optional
or
nullOptional
pfpany ofOptional

The agent's profile picture as base64 encoded PNG bytes. The picture must be square and at least 300 * 300 pixels.

string · base64Optional
or
nullOptional
identityany ofOptional

Information about the agent's identity.

or
nullOptional
backgroundany ofOptional

A description of the agent's background.

string · min: 1Optional
or
nullOptional
behaviorsany ofOptional

A list of behavioral guidelines that this agent follows.

string[]Optional
or
nullOptional
communication_patternsany ofOptional

A list of descriptions that illustrate the communication styles of this agent.

string[]Optional
or
nullOptional
voice_configany ofOptional

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.

Default: {}
or
object · _NotSetOptional

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

or
nullOptional
Responses
201
Succeeded.
application/json
400
Attempt to create the initial version for an agent, but not all fields in the request object are defined. Or, the specified voice ID doesn't exist.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or agent does not exist.
409
The specified version is not the expected next version for the agent.
422
Invalid request path parameter, request body, or request query parameter failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/organization/agent/{agent_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 407

{
  "initials": "text",
  "pfp": "text",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "background": "text",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ],
  "voice_config": {
    "voice_id": "text",
    "stability": 1,
    "similarity_boost": 1,
    "style": 1
  }
}
{
  "id": "text",
  "version": 1,
  "created_at": "2025-05-10T09:03:54.240Z"
}

Create a service hierarchical state machine

post

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.

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
state_machine_namestring · min: 1 · max: 256Required

The name of the new state machine.

Responses
201
Succeeded.
application/json
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization does not exist.
409
A state machine with the same name already exists.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/organization/service_hierarchical_state_machine HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "state_machine_name": "text"
}
{
  "id": "text"
}

Create a service hierarchical state machine version

post

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.

Authorizations
Path parameters
service_hierarchical_state_machine_idstringRequired

The ID of the service hierarchical state machine to create a new version for.

Pattern: ^[a-f0-9]{24}$
organizationstringRequired
Query parameters
versionany ofOptional

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.

integer · min: 1Optional
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
Body
descriptionstring · min: 1Required

A description of the service hierarchical state machine.

new_user_initial_statestringRequired

The state a new user will be in when a session starts. This must be an action state, and must be an internal state.

Pattern: ^[A-Za-z0-9_]+$
returning_user_initial_statestringRequired

The state a returning user will be in when a session starts. This must be an action state, and must be an internal state.

Pattern: ^[A-Za-z0-9_]+$
terminal_statestringRequired

The state the user will be in when the session ends. This must be an action state, and must be an internal state.

Pattern: ^[A-Za-z0-9_]+$
global_intra_state_navigation_guidelinesstring[]Required

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.

global_action_guidelinesstring[]Required

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.

global_boundary_constraintsstring[]Required

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.

Responses
201
Succeeded.
application/json
400
The specified state machine version depends on another state machine that either doesn't exist or is deprecated.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or state machine does not exist.
409
The specified version number is not the expected next version for the state machine.
422
Invalid request path parameterl, request body, or request query parameter failed validation.
429
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/organization/service_hierarchical_state_machine/{service_hierarchical_state_machine_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 575

{
  "description": "text",
  "states": {
    "ANY_ADDITIONAL_PROPERTY": {
      "type": "text",
      "objective": "text",
      "actions": [
        "text"
      ],
      "intra_state_navigation_guidelines": [
        "text"
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "exit_conditions": [
        {
          "description": "text",
          "next_state": "text"
        }
      ],
      "message_metadata": [
        "text"
      ]
    }
  },
  "new_user_initial_state": "text",
  "returning_user_initial_state": "text",
  "terminal_state": "text",
  "references": {
    "ANY_ADDITIONAL_PROPERTY": []
  },
  "global_intra_state_navigation_guidelines": [
    "text"
  ],
  "global_action_guidelines": [
    "text"
  ],
  "global_boundary_constraints": [
    "text"
  ]
}
{
  "id": "text",
  "version": 1,
  "created_at": "2025-05-10T09:03:54.240Z"
}

Create an API key

post

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.

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
durationstring · durationRequired

The valid duration of the API key. Should be supplied in the ISO8601 format. Must be between 1 to 90 days.

role_namestringOptional

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.

Default: DefaultAdministratorRole
Responses
201
Succeeded.
application/json
400
The organization has reached the maximum API key limit.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or role does not exist.
422
Invalid request path parameter or request body 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}/organization/api_key/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "duration": "text",
  "role_name": "text"
}
{
  "api_key_id": "text",
  "api_key": "text",
  "expires_at": "2025-05-10T09:03:54.240Z"
}

Get metrics for an organization

post

Compute metrics for an organization.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

  • Organization:GetMetric for the organization.

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
Responses
200
Succeeded.
application/json
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization does not exist.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
post
POST /v1/{organization}/organization/metrics HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "metrics": [
    {
      "type": "text",
      "conversation_count_threshold": 1,
      "starts": "2025-05-10T09:03:54.240Z",
      "ends": "2025-05-10T09:03:54.240Z"
    }
  ]
}
{
  "metrics": [
    {
      "type": "text",
      "active_user_count": 1
    }
  ]
}