Amigo Organization API
The Organization API from Amigo — 11 operation(s) for organization.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account Organization 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: Organization
paths:
/v1/{organization}/organization/:
get:
tags:
- Organization
summary: Get an organization
description: 'Get the details of an organization.
#### Permissions
This endpoint may be impacted by the following permissions:
* The `default_user_preferences` field is only populated if the endpoint is called with user authentication credentials, and the authenticated user has the
`Organization:GetOrganizationDetails` permission.'
operationId: get-organization
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
responses:
'200':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__organization__get_organization__Response'
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter failed validation.
'503':
description: The service is going through temporary maintenance.
security: []
put:
tags:
- Organization
summary: Create an organization
description: "Set up a new organization in the Amigo system. Specifically, it\n* creates a new organization within the Amigo Mongo database with the given details.\n * Along with the new organization, 4 default roles are created:\n * `DefaultUserRole`.\n * `DefaultAdministratorRole`.\n * `DefaultAmigoAdministratorRole`.\n * `DefaultSuperAdministratorRole`.\n * A super user, `admin@amigo.ai`, is created and granted the `DefaultSuperAdministratorRole`.\n* creates a new tenant in Google Identity Platform for users in this organization.\n* creates a new Route53 record, `{org_id}.amigo.ai`, that hosts the Amigo frontend for this organization.\n* creates a new domain, `{org_id}.amigo.ai`, on Vercel.\n\nThe `x-mongo-cluster-name` header is mandatory for this endpoint.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `Organization:CreateOrganization`. for the organization to create."
operationId: create-organization
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: x-mongo-cluster-name
in: header
required: true
schema:
type: string
description: The Mongo cluster name to perform this request in.
title: X-Mongo-Cluster-Name
description: The Mongo cluster name to perform this request in.
- 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__organization__create_organization__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__organization__create_organization__Response'
'422':
description: Invalid request path parameter or request body failed validation.
'409':
description: Conflicts with existing organization with the same `org_id`, or a related operation is in progress.
'400':
description: The specified organization ID is reserved.
'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 5 requests per minute for this endpoint.
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
post:
tags:
- Organization
summary: Modify an organization
description: 'Modify elements of an organization.
#### Permissions
This endpoint requries the following permissions:
* `Organization:ModifyOrganization` to modify the organization.'
operationId: modify-organization
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__organization__modify_organization__Request'
responses:
'204':
description: Succeeded.
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter or request body failed validation.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 10 requests per minute for this endpoint.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
delete:
tags:
- Organization
summary: Delete an organization
description: 'Delete an organization. All of the organization''s data are erased. Some analytical data will be asynchronously removed at
a future date.
Unlike other endpoints, this endpoint is not transactional. If any operation fails during the execution, the endpoint does not
revert the performed actions. The caller should re-call this endpoint until it succeeds.
Regardless of whether this endpoint succeeds or not, the first time this endpoint is called, the organization is considered
deleted. Even if the endpoint fails and the organization isn''t completely wiped, it''s considered in an invalid state and any
other operations on it may fail.
#### Permissions
This endpoint requires the following permissions:
* `Organization:DeleteOrganization` for the organization to delete.'
operationId: delete-organization
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
responses:
'204':
description: Succeeded.
'422':
description: Invalid request path parameter failed validation.
'404':
description: Specified organization is not found.
'401':
description: Invalid authorization credentials.
'400':
description: The current environment or organization does not support this endpoint.
'409':
description: A related operation is in progress.
'403':
description: Missing required permissions.
'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.
/v1/{organization}/organization/agent:
post:
tags:
- Organization
summary: Create an agent
description: '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:
* `Organization:CreateAgent` for the new agent.'
operationId: create-agent
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__organization__create_agent__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__organization__create_agent__Response'
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter or request body failed validation.
'409':
description: An `Agent` with the same name already exists.
'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 10 requests per minute for this endpoint.
get:
tags:
- Organization
summary: Get agents for an organization
description: 'Return a list of agents for the organization.
#### Permissions
This endpoint may be impacted by the following permissions:
* Only agents that the authenticated user has the `Organization:GetAgent` permission on will be returned.'
operationId: get-agents
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: deprecated
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether the agent is deprecated.
title: Deprecated
description: Whether the agent is deprecated.
- name: id
in: query
required: false
schema:
type: array
uniqueItems: true
items:
type: string
pattern: ^[a-f0-9]{24}$
description: The IDs of the agents to filter for.
default: []
title: Id
description: The IDs of the agents to filter for.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 20
exclusiveMinimum: 0
description: The maximum number of agents to return.
default: 10
title: Limit
description: The maximum number of agents to return.
- name: continuation_token
in: query
required: false
schema:
type: integer
description: The continuation token from the previous request used to retrieve the next page of agents.
default: 0
title: Continuation Token
description: The continuation token from the previous request used to retrieve the next page of agents.
- 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__organization__get_agents__Response'
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter or 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 20 requests per minute for this endpoint.
/v1/{organization}/organization/agent/{agent_id}/:
post:
tags:
- Organization
summary: Create an agent version
description: '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:
* `Organization:CreateAgentVersion` for the new version of the agent.'
operationId: create-agent-version
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the agent to create a new version for.
title: Agent Id
description: The ID of the agent to create a new version for.
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: version
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: 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.
title: Version
description: 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.
- 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__organization__create_agent_version__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__organization__create_agent_version__Response'
'404':
description: The specified organization or agent does not exist.
'422':
description: Invalid request path parameter, request body, or request query parameter failed validation.
'409':
description: The specified version is not the expected next version for the agent.
'400':
description: 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':
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 10 requests per minute for this endpoint.
delete:
tags:
- Organization
summary: Delete an agent
description: '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:
* `Organization:DeleteAgent` for the agent to delete.'
operationId: delete-agent
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the agent to delete
title: Agent Id
description: The ID of the agent 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:
'200':
description: Succeeded.
content:
application/json:
schema: {}
'404':
description: The specified organization or agent does not exist.
'400':
description: An active service exists that utilizes this agent.
'409':
description: The specified agent is already deleted
'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 10 requests per minute for this endpoint.
/v1/{organization}/organization/service_hierarchical_state_machine:
post:
tags:
- Organization
summary: Create a service hierarchical state machine
description: '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:
* `Organization:CreateServiceHierarchicalStateMachine` for the new service hierarchical state machine.'
operationId: create-service-hierarchical-state-machine
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__organization__create_service_hierarchical_state_machine__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__organization__create_service_hierarchical_state_machine__Response'
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter or request body failed validation.
'409':
description: A state machine with the same name already exists.
'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 10 requests per minute for this endpoint.
get:
tags:
- Organization
summary: Get service hierarchical state machines for an organization
description: 'Return a list of service hierarchical state machines for the organization.
#### Permissions
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.'
operationId: get-service-hierarchical-state-machines
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: deprecated
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether the state machine is deprecated.
title: Deprecated
description: Whether the state machine is deprecated.
- name: id
in: query
required: false
schema:
type: array
uniqueItems: true
items:
type: string
pattern: ^[a-f0-9]{24}$
description: The IDs of the state machines to filter for.
default: []
title: Id
description: The IDs of the state machines to filter for.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
minimum: 0
description: The maximum number of service hierarchical state machines to return.
default: 50
title: Limit
description: The maximum number of service hierarchical state machines to return.
- name: continuation_token
in: query
required: false
schema:
type: integer
description: The continuation token from the previous request used to retrieve the next page of state machines.
default: 0
title: Continuation Token
description: The continuation token from the previous request used to retrieve the next page of state machines.
- 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__organization__get_service_hierarchical_state_machines__Response'
'404':
description: The specified organization does not exist.
'422':
description: Invalid request path parameter or 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 20 requests per minute for this endpoint.
/v1/{organization}/organization/service_hierarchical_state_machine/{service_hierarchical_state_machine_id}/:
post:
tags:
- Organization
summary: Create a service hierarchical state machine version
description: "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\nconstraints:\n* Each action state must have at least one action.\n* 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,\n 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\n in the states.\n* For `recall`, `reflection`, and `tool_call` 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,\n 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\n in the states.\n* The terminal state cannot have exit conditions and must have exactly one action.\n\nSee the per-request-field documentation for more field-specific constraints.\n\nDue to the complexity of the state machine data structure, this endpoint provides a `dry_run` parameter. If set to `True`, the endpoint will check the supplied state machine would pass validations,\nbut does not actually create a new version. In this case, the endpoint returns an empty response with a 201 status code.\n\n#### Permissions:\nThis endpoint requires the following permissions:\n* `Organization:CreateServiceHierarchicalStateMachineVersion` for the service hierarchical state machine."
operationId: create-service-hierarchical-state-machine-version
parameters:
- name: service_hierarchical_state_machine_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the service hierarchical state machine to create a new version for.
title: Service Hierarchical State Machine Id
description: The ID of the service hierarchical state machine to create a new version for.
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: version
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: 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.
title: Version
description: 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.
- name: dry_run
in: query
required: false
schema:
type: boolean
description: Whether to perform a dry run of the operati
# --- truncated at 32 KB (566 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-organization-api-openapi.yml