Service Discovery + Management
Understanding Amigo Services
Your integration may include multiple service types, each designed for specific interaction scenarios:
Meet & Greet: Optimized for new user onboarding
Adaptive Support: Designed for returning user support
Each service has a unique service ID that must be referenced when creating conversations. Though services may be connected in a workflow (e.g., Meet & Greet leading to Adaptive Support), you must initiate conversations with the correct service ID to ensure proper user experience.
Retrieving Available Services
To discover all available services for your organization:
curl --request GET \
--url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/?limit=10&is_active=true' \
--header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
--header 'Accept: application/json'
The response will contain a list of services with their respective IDs, names, and other metadata.
// sample GET services response
{
"services": [
{
"id": "6618791275130b73714e8d1c",
"name": "Meet & Greet",
"description": "A service that handles a scenario",
"icon": null,
"active_conversation_id": null,
"is_active": true,
"service_hierarchical_state_machine_id": "6618791375530b73714e8d1a",
"agent_id": "6618791275530b73714e9d18",
"conversation_metrics": []
},
... // more services
]
}
Retrieve a list of services in this organization.
Permissions
This endpoint is impacted by the following permissions:
- Only services that the authenticated user has the
Service:GetService
permission for are returned.
The ID of the service to retrieve.
[]
Whether the service is active.
The fields to sort the versions by. Supported fields are name
and is_active
. Specify a +
before the field name to indicate ascending sorting and -
for descending sorting. Multiple fields can be specified to break ties.
[]
The tags of the services. Must be specified using the syntax key:value
, which means to match all services with the given key
and value
pair among its tags. If value
is *
, it means the value
does not matter. If value
is empty, it matches against when the value is None
.
[]
The maximum number of services to return.
10
The continuation token from the previous request used to retrieve the next page of services.
0
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.
[]
Succeeded.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 50 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*
{
"services": [
{
"id": "text",
"name": "text",
"version_sets": {
"ANY_ADDITIONAL_PROPERTY": {
"agent_version_number": 1,
"service_hierarchical_state_machine_version_number": 1,
"llm_model_preferences": {
"ANY_ADDITIONAL_PROPERTY": {
"llm_name": "text",
"top_p": 1,
"temperature": 1,
"top_k": 1
}
}
}
},
"description": "text",
"is_active": true,
"service_hierarchical_state_machine_id": "text",
"agent_id": "text",
"tags": [
{
"key": "text",
"value": "text"
}
]
}
],
"has_more": true,
"continuation_token": 1,
"filter_values": {
"tags": [
"text"
]
}
}
Create a Service
curl --request POST \
--url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/' \
--header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '
{
"service_hierarchical_state_machine_id": "8b5c6599bfb8ffc45646b289",
"agent_id": "0d0b781189c14189526c2603",
"name": "New Service",
"description": "A description",
"is_active": true,
}'
The response will contain the ID of the created service:
{
"id": "6618791275130b73714e8d1c"
}
Create a new service. Depending on whether an active service with the same name already exists, the endpoint behaves differently:
- If
is_active
isFalse
, creates an inactive new service. - If
is_active
isTrue
and no active service with the given name exists, creates a new active service. - If
is_active
isTrue
and an active service with the given name exists, this endpoint throws an error.
The new service will automatically contain an edge
version set that uses the latest Agent
and ServiceHierarchicalStateMachine
versions with no LLM model preference.
It will also create a release
version set, that will equal to what's specified in the request if the release_version_set
is specified, or equal to edge
if not.
Permissions
This endpoint requires the following permissions:
Service:CreateService
for the service to create.Service:CreateVersionSet
for theedge
andrelease
version sets.
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 ID of the state machine that this service uses.
^[a-f0-9]{24}$
The ID of the agent that this service uses.
^[a-f0-9]{24}$
The name of this service.
A description of this service.
Whether the newly-created service is active. Only active services are visible to users on the dashboard. You can later adjust the activeness of this service.
The release
version set to use for this service. If not specified, the release
version set will be the same as the edge
version set, which uses the
latest agent and state machine versions with no model preference.
Succeeded.
This error could be thrown due to the following reasons:
- The specified ID for agent or service hierarchical state machine versions in the
release
version set does not belong to the agent or service hierarchical state machine of the service. - The specified agent or state machine doesn't have any versions.
Invalid authorization credentials.
Missing required permissions.
The specified organization, agent, or service hierarchical state machine do not exist.
An active service with the given name already exists.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 392
{
"service_hierarchical_state_machine_id": "text",
"agent_id": "text",
"name": "text",
"description": "text",
"is_active": true,
"release_version_set": {
"agent_version_number": 1,
"service_hierarchical_state_machine_version_number": 1,
"llm_model_preferences": {
"ANY_ADDITIONAL_PROPERTY": {
"llm_name": "openai_o4-mini-2025-04-16",
"top_p": 1,
"temperature": 1,
"top_k": 1
}
}
},
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
{
"id": "text"
}
Update a Service
To update a service's non-functional metadata, use the following:
curl --request POST \
--url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/<SERVICE-ID>/' \
--header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '
{
"is_active": false,
}'
To change a service's functional fields such as its agent ID, create a new service and delete the old service.
Update fields about a service.
Permissions
This endpoint requires the following permissions:
Service:UpdateService
for the service.
The identifier of the service to update.
^[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.
[]
The name of the service. Only updated if not-null.
A description of this Service
. Only updates if not-null.
The activeness of the service. Only updated if not-null.
If set to True
and the service is currently inactive, no other service with the same name can be active.
If set to False
and the service is currently active, it is deactivated. This will error if the service is used in a simulation unit test.
The ID of the agent that this service uses. Only updated if not-null.
^[a-f0-9]{24}$
The ID of the service hierarchical state machine that this service uses. Only updated if not-null.
^[a-f0-9]{24}$
The tags of this service. Only updated if not-null.
Succeeded.
This may occur for the following reasons:
- The request intends to activate a service that uses a deprecated agent, state machine, or LLM, or it uses an invalid agent or state machine.
- The request intends to deactivate a service that is used in a simulation unit test.
Invalid authorization credentials.
Missing required permissions.
The specified organization or service do not exist.
The request intends to activate a service that has an active service with the same name.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/service/{service_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 160
{
"name": "text",
"description": "text",
"is_active": true,
"agent_id": "text",
"service_hierarchical_state_machine_id": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
No content
Service Mapping Best Practices
For effective service routing in your application:
Service ID Persistence: Store service IDs in your system with descriptive labels
User Journey Mapping: Create logical mappings between user states and appropriate services:
First-time users → Meet & Greet service (e.g. service ID:
67a23a08b02fe1e74341a6f8
)Returning users → Reactive Support service (e.g. service ID:
675769a1d71dbf8cf042271f
)
Dynamic Routing: Implement logic in your application to direct users to the appropriate service based on their status or needs
Service Versioning
When creating new conversations, you can specify the service version:
service_version_set_name
: Typically set to"release"
for production environmentsservice_id
: The unique identifier for the specific service you want to use
This approach ensures users are routed to the correct conversation flow based on their context and needs.
Was this helpful?