Amigo Tool API
The Tool API from Amigo — 10 operation(s) for tool.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amigo Account Tool API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: Tool
paths:
/v1/{organization}/tool/amigo_tool_scaffold.tar.gz:
get:
tags:
- Tool
summary: Get the latest tool scaffold release
operationId: get-tool-scaffold-release
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
responses:
'200':
description: Succeeded.
content:
application/gzip:
schema:
type: string
'404':
description: Specified organization is not found.
'422':
description: Invalid request path parameter failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
/v1/{organization}/tool/:
post:
tags:
- Tool
summary: Create a new tool
description: '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:CreateTool` for the tool to create.'
operationId: create-tool
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__create_tool__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__create_tool__Response'
'404':
description: The specified organization does not exist.
'409':
description: A tool with the same name already exists.
'422':
description: Invalid request path parameter or request body failed validation.
'400':
description: The tool name is too long.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
get:
tags:
- Tool
summary: Get tools
operationId: get-tools
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: id
in: query
required: false
schema:
type: array
uniqueItems: true
items:
type: string
pattern: ^[a-f0-9]{24}$
description: The IDs of the tools to retrieve.
default: []
title: Id
description: The IDs of the tools to retrieve.
- name: deprecated
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether the tools are deprecated.
title: Deprecated
description: Whether the tools are deprecated.
- name: sort_by
in: query
required: false
schema:
type: array
items:
type: string
description: 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.
default: []
title: Sort By
description: 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.
- name: tag
in: query
required: false
schema:
type: array
items:
type: string
description: 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`.
default: []
title: Tag
description: 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`.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 20
exclusiveMinimum: 0
description: The maximum number of tools to return.
default: 10
title: Limit
description: The maximum number of tools to return.
- name: continuation_token
in: query
required: false
schema:
type: integer
description: The continuation token from the previous request used to retrieve the next page of tools.
default: 0
title: Continuation Token
description: The continuation token from the previous request used to retrieve the next page of tools.
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
responses:
'200':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__get_tools__Response'
'404':
description: Specified organization is not found.
'422':
description: Invalid request path parameter or request query parameter failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
/v1/{organization}/tool/{tool_id}/version/{versions}:
delete:
tags:
- Tool
summary: Deprecate tool versions
description: 'Deprecate tool versions that match the specified semver constraint.
#### Permissions
This endpoint requires the following permissions:
* `Tool:ModifyTool` on the tool whose versions to deprecate.'
operationId: deprecate-tool-version
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to deprecate.
title: Tool Id
description: The ID of the tool to deprecate.
- name: versions
in: path
required: true
schema:
type: string
description: A semver constraint that specifies the version to deprecate in the [Python packaging specification](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5). All versions that match this constraint will be deprecated.
title: Versions
description: A semver constraint that specifies the version to deprecate in the [Python packaging specification](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5). All versions that match this constraint will be deprecated.
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
responses:
'204':
description: Succeeded.
'404':
description: The specified organization or tool does not exist.
'422':
description: Invalid request path parameter or request body failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
/v1/{organization}/tool/{tool_id}:
delete:
tags:
- Tool
summary: Deprecate a tool
description: '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:DeleteTool` on the tool to deprecate.'
operationId: deprecate-tool
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to deprecate.
title: Tool Id
description: The ID of the tool to deprecate.
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
responses:
'204':
description: Succeeded.
'404':
description: The specified organization or tool does not exist.
'409':
description: A related operation is in progress.
'422':
description: Invalid request path parameter or request body failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
post:
tags:
- Tool
summary: Modify a tool
description: 'Modify basic properties of a tool, such as its description and tags.
#### Permissions
This endpoint requires the following permissions:
* `Tool:ModifyTool` for the tool to modify.'
operationId: modify-tool
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to modify
title: Tool Id
description: The ID of the tool to modify
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__modify_tool__Request'
responses:
'204':
description: Succeeded.
'404':
description: The specified organization or tool does not exist.
'422':
description: Invalid request path parameter or request body failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
/v1/{organization}/tool/test:
post:
tags:
- Tool
summary: Test a tool
operationId: test-tool
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__test_tool__Request'
responses:
'200':
description: Succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__test_tool__Response'
'404':
description: The specified organization or tool commit does not exist.
'400':
description: "This error can occur due to the following reasons:\n * An environment variable is specified as both secret and non-secret.\n * The specified tool commit failed CI checks.\n * Required environment variables in the tool are not declared in the reqeust.\n * Input parameters do not conform to the tool's input schema.\n * Tool build failed.\n "
'422':
description: Invalid request path parameter or request body failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 1 request per minute for this endpoint.
/v1/{organization}/tool/{tool_id}/envvar:
post:
tags:
- Tool
summary: Modify the environment variables of a tool
description: '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:ModifyTool` for the tool whose environment variables to modify.'
operationId: modify-tool-envvars
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to modify
title: Tool Id
description: The ID of the tool to modify
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__modify_tool_envvars__Request'
responses:
'204':
description: Succeeded.
'404':
description: The specified organization or tool does not exist.
'409':
description: An environment variable with the same name as the one to insert exists or has been recently deleted.
'400':
description: The specified environment variables to update or delete do not exist, or the environment variables to delete are used by non-deprecated tool versions.
'422':
description: Invalid request body or request path parameter.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 20 requests per minute for this endpoint.
/v1/{organization}/tool/{tool_id}/version:
post:
tags:
- Tool
summary: Publish a new version of a tool
description: '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:ModifyTool` for the tool.'
operationId: publish-tool-version
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to publish
title: Tool Id
description: The ID of the tool to publish
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__publish_tool_version__Request'
responses:
'201':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__publish_tool_version__Response'
'404':
description: The specified organization, tool, commit, or project directory does not exist.
'400':
description: Specified commit is older than the last valid commit, or the environment variables required by the tool version do not exist on the tool, or more than 3 active versions of the tool exist, or tool build has failed.
'409':
description: A related operation is in progress.
'422':
description: Invalid request path parameter or request body failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 10 requests per minute for this endpoint.
get:
tags:
- Tool
summary: Get tool versions
operationId: get-tool-versions
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the tool to retrieve versions for.
title: Tool Id
description: The ID of the tool to retrieve versions for.
- name: deprecated
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Whether to filter by deprecated tool versions.
title: Deprecated
description: Whether to filter by deprecated tool versions.
- name: versions
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: A semver constraint that specifies the versions to retrieve.
title: Versions
description: A semver constraint that specifies the versions to retrieve.
- name: sort_by
in: query
required: false
schema:
type: array
items:
type: string
description: '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. '
default: []
title: Sort By
description: '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. '
- name: creator
in: query
required: false
schema:
type: array
uniqueItems: true
items:
type: string
description: The creators of the tool versions. Each value must be of the format `org_id,user_id`.
default: []
title: Creator
description: The creators of the tool versions. Each value must be of the format `org_id,user_id`.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
minimum: 0
description: The maximum number of tool versions to return.
default: 50
title: Limit
description: The maximum number of tool versions to return.
- name: continuation_token
in: query
required: false
schema:
type: integer
description: The continuation token from the previous request used to retrieve the next page of tool versions.
default: 0
title: Continuation Token
description: The continuation token from the previous request used to retrieve the next page of tool versions.
- name: x-mongo-cluster-name
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 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.
title: X-Mongo-Cluster-Name
description: 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.
- name: Sec-WebSocket-Protocol
in: header
required: false
schema:
type: array
items:
type: string
default: []
title: Sec-Websocket-Protocol
responses:
'200':
description: Succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/src__app__endpoints__tool__get_tool_versions__Response'
'404':
description: Specified organization or tool is not found.
'422':
description: Invalid request path parameter or request query parameter failed validation.
'401':
description: Invalid authorization credentials.
'403':
description: Missing required permissions.
'503':
description: The service is going through temporary maintenance.
'429':
description: The user has exceeded the rate limit of 50 requests per minute for this endpoint.
/v1/{organization}/tool/invocation:
get:
tags:
- Tool
summary: Get tool invocations
description: 'Retrieve tool invocations under the specified filters.
#### Permissions
This endpoint may require the following permission:
* `Conversation:GetInteractionInsights` for `ToolInvocation`s from a regular conversation.
* `Simulation:GetSimulationUnitTestSetRun` for `ToolInvocation`s from a simulation conversation.'
operationId: get-tool-invocations
parameters:
- name: organization
in: path
required: true
schema:
type: string
title: Organization
- name: tool_id
in: query
required: false
schema:
type: array
uniqueItems: true
items:
type: string
pattern: ^[a-f0-9]{24}$
description: The IDs of the tools to get invocations for.
default: []
title: Tool Id
description: The IDs of the tools to get invocations for.
- name: version
in: query
required: false
schema:
type: array
items:
type: string
description: A list of semver constraints that specifies the versions to retrieve in the [Python packaging specification](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5). This must be the exact same length as `tool_id`, and each entry corresponds to the tool ID at the same index.
default: []
title: Version
description: A list of semver constraints that specifies the versions to retrieve in the [Python packaging specification](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5). This must be the exact same length as `tool_id`, and each entry corresponds to the tool ID at the same index.
- name: invocation_source_type
in: query
required: false
schema:
type: array
uniqueItems: true
items:
enum:
- regular-conversation
- simulation-conversation
type: string
description: The source types of the invocations.
default: []
title: Invocati
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-tool-api-openapi.yml