Tool
The ID of the tool to retrieve.
[]Whether the tools are deprecated.
The fields to sort the versions by. Supported fields are name and deprecated. 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 simulation personas. Must be specified using the syntax key:value, which means to match all sets 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 tools to return.
10The continuation token from the previous request used to retrieve the next page of tools.
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.
Invalid authorization credentials.
Missing required permissions.
Specified organization is not found.
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}/tool/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"tools": [
{
"id": "text",
"org_id": "text",
"created_at": "2025-10-21T15:10:59.432Z",
"updated_at": "2025-10-21T15:10:59.432Z",
"name": "text",
"description": "text",
"deprecated": true,
"envvars": [
"text"
],
"secret_envvars": [
"text"
],
"tags": [
{
"key": "text",
"value": "text"
}
]
}
],
"has_more": true,
"continuation_token": null,
"filter_values": {
"tags": [
"text"
]
}
}Create a new tool. The tool will not contain any versions initially so is not usable until at least one version is published.
Permissions
This endpoint requires the following permissions:
Tool:CreateToolfor the tool to create.
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 tool. It must be unique among all non-deprecated tools in the organization.
^[a-z0-9_]+$A description of the tool.
Succeeded.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
A tool with the same 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}/tool/ 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: 78
{
"name": "text",
"description": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"id": "text"
}Deprecate tool versions that match the specified semver constraint.
Permissions
This endpoint requires the following permissions:
Tool:ModifyToolon the tool whose versions to deprecate.
The ID of the tool to deprecate.
^[a-f0-9]{24}$A semver constraint that specifies the version to deprecate in the Python packaging specification. All versions that match this constraint will be deprecated.
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.
No content
Invalid authorization credentials.
Missing required permissions.
The specified organization or tool does not exist.
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.
DELETE /v1/{organization}/tool/{tool_id}/version/{versions} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
Modify basic properties of a tool, such as its description and tags.
Permissions
This endpoint requires the following permissions:
Tool:ModifyToolfor the tool to modify.
The ID of the tool to modify
^[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.
[]A description of this tool. Only updates if not-null.
The tags of this tool. Only updates if not-null.
Succeeded.
No content
Invalid authorization credentials.
Missing required permissions.
The specified organization or tool does not exist.
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}/tool/{tool_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: 64
{
"description": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}No content
Deprecate the specified tool. All versions of the tool will be deprecated and the tool will no longer be used.
After the endpoint concludes, the deprecation will take around 1 minute to propagate across the system.
Permissions
This endpoint requires the following permissions:
Tool:DeleteToolon the tool to deprecate.
The ID of the tool to deprecate.
^[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.
[]Succeeded.
No content
Invalid authorization credentials.
Missing required permissions.
The specified organization or tool does not exist.
A related operation is in progress.
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.
DELETE /v1/{organization}/tool/{tool_id} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
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 branch in the tools repo whose tip will be tested.
The directory in the tools repo that contains the pyproject.toml file corresponding to the tool version to publish.
^[-\w\d_/]+$Succeeded
This error can occur due to the following reasons: * An environment variable is specified as both secret and non-secret. * The specified tool commit failed CI checks. * Required environment variables in the tool are not declared in the reqeust. * Input parameters do not conform to the tool's input schema.
Invalid authorization credentials.
Missing required permissions.
The specified organization or tool commit does not exist.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 1 request per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/tool/test 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: 260
{
"inputs": [
{
"input_parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"invocation_mode": "regular"
}
],
"commit_branch": "text",
"project_path": "text",
"required_envvars": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"required_secret_envvars": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"invocation_results": [
{
"succeeded": true,
"output": "text",
"duration_ms": 1
}
]
}Add, update, or delete the environment variables of a tool. Environment variables must be present in the tool before any versions requiring them can be published.
You cannot delete variables that are required by non-deprecated tool versions.
Permissions
This endpoint requires the following permissions:
Tool:ModifyToolfor the tool whose environment variables to modify.
The ID of the tool to modify
^[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.
[]Succeeded.
No content
The specified environment variables to update or delete do not exist, or the environment variables to delete are used by non-deprecated tool versions.
Invalid authorization credentials.
Missing required permissions.
The specified organization or tool does not exist.
An environment variable with the same name as the one to insert exists or has been recently deleted.
Invalid request body or request path parameter.
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}/tool/{tool_id}/envvar 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: 132
{
"inserts": [
{
"name": "text",
"value": "text",
"is_secret": true
}
],
"updates": [
{
"name": "text",
"value": "text"
}
],
"deletes": [
{
"name": "text"
}
]
}No content
The ID of the tool to retrieve versions for.
^[a-f0-9]{24}$Whether the tools are deprecated.
A semver constraint that specifies the version to retrieve in the Python packaging specification. If not specified, all versions will be retrieved.
The fields to sort the versions by. Supported fields are created_at, version.major, version.minor, version.patch, and deprecated. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The creators of the tool versions. Each value must be of the format org_id,user_id.
[]The maximum number of tool versions to return.
50The continuation token from the previous request used to retrieve the next page of tool versions.
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.
Invalid authorization credentials.
Missing required permissions.
Specified organization or tool is not found.
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}/tool/{tool_id}/version HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"tool_versions": [
{
"id": "text",
"org_id": "text",
"created_at": "2025-10-21T15:10:59.432Z",
"updated_at": "2025-10-21T15:10:59.432Z",
"tool_id": "text",
"version": {
"major": 1,
"minor": 1,
"patch": 1
},
"required_envvars": [
"text"
],
"required_secret_envvars": [
"text"
],
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_repo": "main",
"tool_commit_hash": "text",
"amigo_scaffold_commit_hash": "text",
"project_directory": "text",
"lambda_version": 1,
"creator": {
"user_id": "text",
"user_org_id": "text"
},
"deprecated": true
}
],
"has_more": true,
"continuation_token": null,
"filter_values": {
"creators": [
{
"user_id": "text",
"user_org_id": "text"
}
]
}
}Publish a new version of the specified tool. After this endpoint finishes, the new version will be immediately available for use.
This endpoint will take roughly 1-5 minutes to complete, so please adjust the timeout settings of your HTTP client accordingly.
Permissions
This endpoint requires the following permissions:
Tool:ModifyToolfor the tool.
The ID of the tool to publish
^[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 repo to publish the tool version from. If team, then it's published from the repo of the organization's Azure DevOps team. If main, then it's published
from the tools-main repo.
The directory in the tools repo that contains the pyproject.toml file corresponding to the tool version to publish.
^[-\w\d_/]+$The type of bump to apply to the version. For initial version of the tool, use major.
Succeeded.
Specified commit is older than the last valid commit, or the environment variables required by the tool version do not exist on the tool.
Invalid authorization credentials.
Missing required permissions.
The specified organization, tool, commit, or project directory does not exist.
A related operation is in progress.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/tool/{tool_id}/version 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: 57
{
"repo": "main",
"project_path": "text",
"bump_type": "major"
}{
"new_version": "text"
}Retrieve tool invocations under the specified filters.
Permissions
This endpoint may require the following permission:
Conversation:GetInteractionInsightsforToolInvocations from a regular conversation.Simulation:GetSimulationUnitTestSetRunforToolInvocations from a simulation conversation.
The ID of the tool to get invocations for.
[]A list of semver constraint that specifies the version to retrieve in the Python packaging specification. This must be the exact same length as tool_id, and each entry corresponds to the tool ID at the same index.
[]The conversation ID associated with the invocation if it's of invocation source regular-conversation
[]The simulation unit test set run ID associated with the invocation if it's of invocation source simulation-conversation
[]Whether the invocation succeeded
The maximum number of tool invocations to return.
100The continuation token from the previous request used to retrieve the next page of tool invocations.
0The fields to sort the versions by. Supported fields are created_at, version.major, version.minor, version.patch, tool_id, invocation_source.type, and invocation_status.succeeded. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]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.
The tool_id and version query parameters are not the same length.
Invalid authorization credentials.
Missing required permissions.
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}/tool/invocation HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"tool_invocations": [
{
"id": "text",
"org_id": "text",
"created_at": "2025-10-21T15:10:59.432Z",
"updated_at": "2025-10-21T15:10:59.432Z",
"invocation_status": {
"succeeded": true,
"output": "text"
},
"invocation_source": {
"type": "regular-conversation",
"user_id": "text",
"conversation_id": "text",
"interaction_id": "text",
"invocation_metadata": {
"type": "state-transition",
"current_state_machine_and_version": [],
"state_name": "text",
"state_transition_index": 1,
"tool_call_round_index": 1
}
},
"logs": [
"text"
],
"duration_ms": 1,
"tool_id": "text",
"tool_version": {
"major": 1,
"minor": 1,
"patch": 1
}
}
],
"has_more": true,
"continuation_token": null
}Invoke a specified tool version with the given input parameters.
Permissions
This endpoint requires the following permissions:
Tool:InvokeToolfor the tool to invoke.
The ID of the tool to invoke
^[a-f0-9]{24}$The version of the tool to invoke
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
The input parameters do not conform to the tool's input schema.
Invalid authorization credentials.
Missing required permissions.
The specified organization, tool, or tool version does not exist.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/tool/{tool_id}/version/{version}/invoke 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: 100
{
"inputs": [
{
"input_parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"invocation_mode": "regular"
}
]
}{
"invocation_results": [
{
"succeeded": true,
"output": "text",
"duration_ms": 1
}
]
}The search query.
The ID of the tool to get invocations for.
[]The conversation ID associated with the invocation if it's of invocation source regular-conversation
[]The simulation unit test set run ID associated with the invocation if it's of invocation source simulation-conversation
[]Whether the invocation succeeded
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 organization is not found.
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}/tool/invocation/search?query=text&query_against=invocation_status.exception_message HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"tool_invocations": [
{
"id": "text",
"org_id": "text",
"created_at": "2025-10-21T15:10:59.432Z",
"updated_at": "2025-10-21T15:10:59.432Z",
"invocation_status": {
"succeeded": true,
"output": "text"
},
"invocation_source": {
"type": "regular-conversation",
"user_id": "text",
"conversation_id": "text",
"interaction_id": "text",
"invocation_metadata": {
"type": "state-transition",
"current_state_machine_and_version": [],
"state_name": "text",
"state_transition_index": 1,
"tool_call_round_index": 1
}
},
"logs": [
"text"
],
"duration_ms": 1,
"tool_id": "text",
"tool_version": {
"major": 1,
"minor": 1,
"patch": 1
}
}
]
}Last updated
Was this helpful?