Services
Understanding Amigo Services
Service Routing Flow
Retrieving Available Services
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'from amigo_sdk import AmigoClient
from amigo_sdk.models import GetServicesParametersQuery
with AmigoClient() as client:
services = client.service.get_services(
GetServicesParametersQuery(limit=10, is_active=True)
)
for service in services.services:
print(f"Service: {service.name} (ID: {service.id})")import { AmigoClient } from "@amigo-ai/sdk";
const client = new AmigoClient({ ...config });
const services = await client.services.getServices({
limit: 10,
is_active: true,
});
services.services?.forEach((service) => {
console.log(`Service: ${service.name} (ID: ${service.id})`);
});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:GetServicepermission for are returned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The IDs of the services to retrieve.
[]Whether the service is active.
The fields to sort the services 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 to filter the services by. 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.
10The continuation token from the previous request used to retrieve the next page of services.
0The 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.
Whether there are more services to retrieve.
A token to supply to the next request to retrieve the next page of services. Only populated if has_more is True.
For each filter that this endpoint supports that can take on dynamic values, this field includes what these values are. This is only provided for the first page in the pagination results.
Note that the values are counted assuming the authenticated user has access to all the services, so they might differ from how many services are actually retrieved.
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.
Create a Service
Create a new service. Depending on whether an active service with the same name already exists, the endpoint behaves differently:
- If
is_activeisFalse, creates an inactive new service. - If
is_activeisTrueand no active service with the given name exists, creates a new active service. - If
is_activeisTrueand 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:CreateServicefor the service to create.Service:CreateVersionSetfor theedgeandreleaseversion sets.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another 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.
[]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.
A list of keyterms that are easy to get wrong during audio transcriptions that tend to occur commonly in audio sessions using this service.
Succeeded.
This error could be thrown due to the following reasons:
- The specified ID for agent or service hierarchical state machine versions in the
releaseversion 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.
- The specified LLM config is invalid.
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.
Update a Service
Update fields about a service.
Permissions
This endpoint requires the following permissions:
Service:UpdateServicefor the service.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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.
A list of keyterms that are easy to get wrong during audio transcriptions that tend to occur commonly in audio sessions using 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.
No content
Service Mapping Best Practices
Service Versioning with Version Sets
What are Version Sets?
Using Version Sets
Dynamic Behaviors
Key Concepts
Common Use Cases
Integration with Services
Last updated
Was this helpful?