LogoLogo
Go to website
  • Welcome
  • Getting Started
    • Amigo Overview
      • System Components
      • Overcoming LLM Limitations
      • [Advanced] Future-Ready Architecture
      • [Advanced] The Accelerating AI Landscape
    • The Journey with Amigo
      • Partnership Model
  • Concepts
    • Agent Core
      • Core Persona
      • Global Directives
    • Context Graphs
      • State-Based Architecture
      • [Advanced] Field Implementation Guidance
    • Functional Memory
      • Layered Architecture
      • User Model
      • [Advanced] Recall Mechanisms
      • [Advanced] Analytical Capabilities
    • Dynamic Behaviors
      • Side-Effect Architecture
      • Knowledge
      • [Advanced] Behavior Chaining
    • Evaluations
      • Testing Framework Examples
    • [Advanced] Reinforcement Learning
    • Safety
  • Glossary
  • Advanced Topics
    • Transition to Neuralese Systems
    • Agent V2 Architecture
  • Agent Building Best Practices
    • Dynamic Behaviors Guide
  • Developer Guide
    • Enterprise Integration Guide
      • Authentication
      • User Creation + Management
      • Service Discovery + Management
      • Conversation Creation + Management
      • Data Retrieval + User Model Management
      • Webhook Management
    • API Reference
      • V1/organization
      • V1/service
      • V1/conversation
      • V1/user
      • V1/role
      • V1/admin
      • V1/webhook_destination
      • V1/metric
      • V1/dynamic_behavior_set
      • V1/simulation
      • Models
Powered by GitBook
LogoLogo

Resources

  • Pricing
  • About Us

Company

  • Careers

Policies

  • Terms of Service

Amigo Inc. ©2025 All Rights Reserved.


On this page

Was this helpful?

Export as PDF
  1. Developer Guide
  2. API Reference

V1/service

PreviousV1/organizationNextV1/conversation

Was this helpful?

Delete a service version set

delete

Delete the given verion set from the given service.

This endpoint will error if the version set is used in any simulation unit tests.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

  • Service:GetService for the service.

  • Service:DeleteVersionSet for the version set.

Authorizations
Path parameters
organizationstringRequired
service_idstringRequired

Identifier of the service.

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

Name of the version set.

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
Responses
204
Succeeded.
400
The specified version set is used in a simulation unit test.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization, service, or version set do not exist.
422
Invalid request path parameter failed validation.
429
The user has exceeded the rate limit of 30 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
delete
DELETE /v1/{organization}/service/{service_id}/version_sets/{version_set_name}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

No content

  • GETGet services
  • POSTCreate a service
  • PUTUpsert a service version set
  • DELETEDelete a service version set
  • POSTUpdate a service

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
Path parameters
organizationstringRequired
Query parameters
idany ofOptional

The ID of the service to retrieve.

string[]Optional
or
nullOptional
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: []
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
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
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",
      "icon": "text",
      "is_active": true,
      "service_hierarchical_state_machine_id": "text",
      "agent_id": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

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

or
nullOptional
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.

string · base64Optional
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
POST /v1/{organization}/service/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 363

{
  "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-11-20",
        "top_p": 1,
        "temperature": 1,
        "top_k": 1
      }
    }
  },
  "icon": "text"
}
{
  "id": "text"
}

Upsert a service version set

put

Upsert a version set for the specified service. Replace the existing version set with the same name if any, or create a new one.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

  • Service:GetService for the service.

This endpoint may require the following permissions:

  • Service:CreateVersionSet if the version set does not exist.

  • Service:UpdateVersionSet if the version set already exists.

  • Organization:GetAgent for the agent if an agent version is specified.

  • Organization:GetServiceHierarchicalStateMachine for the service hierarchical state machine if a service hierarchical state machine verion is specified.

Authorizations
Path parameters
service_idstringRequired

Identifier of the service.

Pattern: ^[a-f0-9]{24}$
version_set_namestring · min: 1Required

Name of the version set to upsert.

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
Body
Responses
204
Succeeded.
400
The agent or service hierarchical state machine version in the request do not belong to the `Agent` or `ServiceHierarchicalStateMachine` of the `Service`.
401
Invalid authorization credentials.
403
Missing required permissions.
404
The specified organization or service do not exist.
422
Invalid request path parameter or request body failed validation.
429
The user has exceeded the rate limit of 30 requests per minute for this endpoint.
503
The service is going through temporary maintenance.
put
PUT /v1/{organization}/service/{service_id}/version_sets/{version_set_name}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "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-11-20",
        "top_p": 1,
        "temperature": 1,
        "top_k": 1
      }
    }
  }
}

No content

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
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
Body
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
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: {}
string · base64Optional
or
object · _NotSetOptional

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

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
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
POST /v1/{organization}/service/{service_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "name": "text",
  "description": "text",
  "icon": "text",
  "is_active": true,
  "agent_id": "text",
  "service_hierarchical_state_machine_id": "text"
}

No content