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
  ]
}

Get services

get

Retrieve a list of services in this organization.

Permissions

This endpoint requires the following permissions:

• User:GetUserInfo for the authenticated user.

This endpoint is impacted by the following permissions:

• Only services that the authenticated user has the Service:GetService permission for are returned.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

organizationstringrequired

Query parameters

idany ofoptional

The ID of the service to retrieve.

is_activeany ofoptional

Whether the service is active.

sort_bystring[]optional

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.

Default: []

limitinteger · min: 1 · max: 20optional

The maximum number of services to return.

Default: 10

continuation_tokenintegeroptional

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

Default: 0

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.amigo.ai/v1/{organization}/service/' \
  --header 'Authorization: Bearer JWT'

200

401

403

404

422

429

503

200

{
  "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",
      "icon": "text",
      "is_active": true,
      "service_hierarchical_state_machine_id": "text",
      "agent_id": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Succeeded.

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 service

post

Create a new service. Depending on whether an active service with the same name already exists, the endpoint behaves differently:

• If is_active is False, creates an inactive new service.
• If is_active is True and no active service with the given name exists, creates a new active service.
• If is_active is True 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:

• User:GetUserInfo for the authenticated user.
• Service:CreateService for the service to create.
• Organization:GetAgent for the specified agent.
• Organization:GetServiceHierarchicalStateMachine for the specified service hierarchical state machine.
• Service:CreateVersionSet for the edge and release version sets.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

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.

Body

service_hierarchical_state_machine_idstringrequired

The ID of the state machine that this service uses.

Pattern: ^[a-f0-9]{24}$

agent_idstringrequired

The ID of the agent that this service uses.

Pattern: ^[a-f0-9]{24}$

namestring · min: 1required

The name of this service.

descriptionstring · min: 1required

A description of this service.

is_activebooleanrequired

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.

release_version_setany ofoptional

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.

iconany ofoptional

The icon to assign to a service. It will be displayed on the dashboard page if set. If not set, a default icon will be used. The icon must be a square-sized PNG file with at least 40 * 40 pixels resolution.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/service/' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "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_gpt-4o-2024-08-06",
          "top_p": 1,
          "temperature": 1,
          "top_k": 1
        }
      }
    },
    "icon": "text"
  }'

201

400

401

403

404

409

422

429

503

201

{
  "id": "text"
}

Succeeded.

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 a service

post

Update fields about a service.

Permissions

This endpoint requires the following permissions:

• User:GetUserInfo for the authenticated user.
• Service:UpdateService for the service.

This endpoint may require the following permissions:

• Organization:GetAgent for the specified agent, if any.
• Organization:GetServiceHierarchicalStateMachine for the specified service hierarchical state machine, if any.

Authorizations

Bearer-AuthorizationBearer-Authorization-OrganizationAPI-Key-Authorization-KeyAPI-Key-Authorization-IDAPI-Key-Authorization-UserID

Path parameters

service_idstringrequired

The identifier of the service to update.

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.

Body

nameany ofoptional

The name of the service. Only updated if not-null.

descriptionany ofoptional

A description of this Service. Only updates if not-null.

iconany ofoptional

The icon to assign to a service. It will be displayed on the dashboard page if set. If not set, a default icon will be used. The icon must be a square-sized PNG file with at least 40 * 40 pixels resolution.

If not specified or set to an empty object, the field is not updated.

Default: {}

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

is_activeany ofoptional

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.

agent_idany ofoptional

The ID of the agent that this service uses. Only updated if not-null.

service_hierarchical_state_machine_idany ofoptional

The ID of the service hierarchical state machine that this service uses. Only updated if not-null.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.amigo.ai/v1/{organization}/service/{service_id}/' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "description": "text",
    "icon": "text",
    "is_active": true,
    "agent_id": "text",
    "service_hierarchical_state_machine_id": "text"
  }'

200

400

401

403

404

409

422

429

503

200

No body

Succeeded.

Service Mapping Best Practices

For effective service routing in your application:

1. Service ID Persistence: Store service IDs in your system with descriptive labels

2. 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)

3. 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 environments

• service_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.