Services

Understanding Amigo Services

Service Types

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.

Architectural Context Services are configured with Context Graphs (the API may refer to these as "state machines") that define how agents navigate problem spaces. Learn more about Context Graphs in our Conceptual Documentation.

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.

Service Routing Flow

Retrieving Available Services

To discover all available services for your organization:

cURL

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'

Python SDK

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})")

Note: Async version also available with async with AsyncAmigoClient()

TypeScript SDK

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})`);
});

The response will contain a list of services with their respective IDs, names, and other metadata.

{
  "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": []
    }
  ]
}

Get services

get

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.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

organizationstringRequired

Query parameters

idstring[]Optional

The ID of the service to retrieve.

Default: []

is_activeany ofOptional

Whether the service is active.

booleanOptional

or

nullOptional

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: []

tagstring[]Optional

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.

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.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

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 query 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

HTTPcURLJavaScriptPython

GET /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
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 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:

• Service:CreateService for the service to create.
• Service:CreateVersionSet for the edge and release version sets.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-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.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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.

or

nullOptional

Responses

201

Succeeded.

application/json

400

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.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization, agent, or service hierarchical state machine do not exist.

409

An active service with the given name already exists.

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

HTTPcURLJavaScriptPython

POST /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
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 a service

post

Update fields about a service.

Permissions

This endpoint requires the following permissions:

• Service:UpdateService for the service.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-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.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

nameany ofOptional

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

string · min: 1Optional

or

nullOptional

descriptionany ofOptional

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

string · min: 1Optional

or

nullOptional

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. This will error if the service is used in a simulation unit test.

booleanOptional

or

nullOptional

agent_idany ofOptional

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

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

or

nullOptional

service_hierarchical_state_machine_idany ofOptional

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

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

or

nullOptional

tagsany ofOptional

The tags of this service. Only updated if not-null.

or

nullOptional

Responses

200

Succeeded.

application/json

Responseany

400

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.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization or service do not exist.

409

The request intends to activate a service that has an active service with the same name.

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

HTTPcURLJavaScriptPython

POST /v1/{organization}/service/{service_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
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

Effective Service Routing

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 with Version Sets

Services use version sets to manage deployments across different environments. Each service can have multiple version sets (e.g., "release", "staging", "dev"), allowing you to test and promote changes without modifying the service ID.

What are Version Sets?

A version set is a named configuration that selects specific versions of:

• Agent (agent_id + version number)

• Context Graph (service_hierarchical_state_machine_id + version number)

• LLM Model Preferences (model configuration for this deployment)

This enables safe, controlled deployment:

Service: "Customer Support"
├─ Version Set: "release" → Agent v2.1, Context Graph v3.0, gpt-5
├─ Version Set: "staging" → Agent v2.2, Context Graph v3.1, claude-sonnet-4-5
└─ Version Set: "dev" → Agent v3.0, Context Graph v4.0, gemini-2.5-pro

Using Version Sets

When creating conversations, specify the version set:

• service_version_set_name: The version set to use (typically "release" for production)

• service_id: The unique identifier for the service

Example:

{
  "service_id": "6618791275130b73714e8d1c",
  "service_version_set_name": "release"
}

This approach ensures:

• Stable production via the "release" version set

• Safe testing via "staging" or "dev" version sets

• Zero-downtime deployments by updating version sets without changing service_id

• Easy rollback by reverting version set configurations

For more on managing version sets and promotion workflows, see Version Sets Best Practices.