Tools
Create, publish, version, and invoke organization-scoped tools with environment variables and Git integration.
Manage organization-scoped, versioned capabilities ("tools"). This page documents the core API endpoints and expected request/response shapes.
Scope and Behavior
All operations are organization-scoped.
Related operations are serialized per tool. Concurrent publish or deprecate calls on the same tool return HTTP 409.
Tool output visibility is controlled by the
result_persistenceproperty configured in Context Graph tool call specifications (see Tool Result Persistence).
How Tools Work (Actions)
Tools run as versioned actions. At a high level:
Versioned builds: when you publish, the platform builds your tool from the organization's tools repository and creates a new immutable version (semantic versioning).
Org-scoped execution: each organization's tools and versions are isolated and only callable within that org.
Managed runtime per execution: runs execute in a managed environment with the variables you configured for the tool. Tool state is versioned and not persisted between runs.
Typed contracts: your tool project defines inputs, outputs, and checks. Publishing runs validations and fails if required pieces are missing.
Configuration first: environment variables (regular and secret) must exist on the tool before publishing versions that require them. In-use variables cannot be deleted.
Rollout control: publishing adds a new version alongside older ones. You choose when to deprecate specific versions or the entire tool. Deprecation removes those versions from new runs.
Observability and traceability: each version records who published it and the pinned source details. Use your org's monitoring to track latency, errors, and usage by version.
Execution Modes
Tools have two execution modes, defined by the invocation_mode parameter when invoking a tool:
regular: Used for production conversations with real users. Tools should perform actual operations (API calls, database updates, external integrations, etc.) in this mode.conversation-simulation: Used for testing and simulation scenarios. Tools may need to mock external calls, use test data, or adjust behavior to avoid side effects during automated testing.
When implementing a tool, handle both modes appropriately in your code. The invocation_mode is passed as part of each input in the invocation request and can be accessed within your tool's execution logic to determine the appropriate behavior.
Tool Entry Point Signature
Your tool implements the scaffold's run_tool() method with the following parameters:
input
The typed input parameters passed to the tool
non_secret_env
The tool's non-secret environment variables
secret_env
The tool's secret environment variables
mode
The invocation mode (regular or conversation-simulation)
user_variables
Key-value pairs configured on the user's profile, useful for external system IDs and tool-specific settings
Tools whose entry point omits the user_variables parameter (the older signature) fail CI checks during publishing.
Typical lifecycle
Create the tool (name, description, tags).
Add required environment variables for the tool.
Test the tool from a branch before publishing.
Publish a version from your team branch (choose major/minor/patch).
Invoke directly or call from your application/SDK.
Query invocation history for debugging and audit.
Iterate by publishing new versions; deprecate older ones when ready.
Workflow (diagram)
Tool Availability by State
In the standard HSM runtime, the agent sees the tools listed in the current state's tool call specifications, and that state-scoped set changes on transition. Native and realtime runtimes can also attach a runtime-defined set of shared platform or system tools globally. Do not treat state membership as an authorization boundary: runtime authorization, tool enablement, and write-scope checks still decide whether a call can execute.
Tool Result Persistence
When tools are configured in Context Graphs (API: service_hierarchical_state_machine), each tool call specification includes a result_persistence property that controls how tool outputs are stored and made available to the agent across interactions.
Persistence Threshold
The persistence threshold is 5,000 characters for the "persisted" and "persisted-preferred" modes.
Example Configuration
Best Practices
Prefer
"persisted-preferred"for most tools: it provides the best balance between context availability and graceful handling of large outputs.Use
"ephemeral"for large or transient data: tools returning large datasets, file contents, or verbose debugging information should use"ephemeral"to prevent context bloat and keep agent performance efficient.Use
"persisted"for critical context: tools whose outputs are essential for conversation continuity (user account lookups, order status, entity resolution) should use"persisted"to guarantee agent access to results.Design concise tool outputs: structure outputs to stay under 5k characters when possible by returning summaries, structured data, or references rather than full raw content.
Create a Tool
Create a new tool with metadata (name, description, tags).
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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.
The ID of the tool.
The tool name is too long.
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"
}List Tools
Common filters:
id=<id>(repeatable),deprecated=true|falsetag=key:value(repeatable;valuemay be*, or empty for null)sort_by=+name|-name|+deprecated|-deprecated(repeatable)limit(1-20, default 10),continuation_token(int, default 0)
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The IDs of the tools 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.
Whether there are more tools to retrieve.
A token to supply to the next request to retrieve the next page of tools. Only populated if has_more is True.
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": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"name": "text",
"description": "text",
"deprecated": true,
"envvars": [
"text"
],
"secret_envvars": [
"text"
],
"tags": [
{
"key": "text",
"value": "text"
}
],
"creator": {
"org_id": "text",
"user_id": "text"
},
"updated_by": {
"org_id": "text",
"user_id": "text"
}
}
],
"has_more": true,
"continuation_token": null,
"filter_values": {
"tags": [
"text"
]
}
}Update a Tool
Update tool metadata (description, tags). Only non-null fields are updated; the tool's name cannot be changed.
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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.
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
Manage Tool Environment Variables
Notes:
Names must match
[A-Z_]+.Variables required by any non-deprecated version cannot be deleted.
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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
Test a Tool
Test a tool from a specific repository branch without publishing. Runs CI checks and executes the tool with supplied inputs.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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. * Tool build failed.
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: 387
{
"inputs": [
{
"input_parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"invocation_mode": "regular",
"nonsensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"sensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"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
}
]
}Publish a Tool Version
Behavior:
Computes next semantic version (or
1.0.0if none), validates, builds, and publishes.Long-running (1-5 minutes). Serialized per tool. Returns 409 if a related operation is in progress.
The request body takes only
project_pathandbump_type(major,minor, orpatch; usemajorfor the first version). Publishing always builds from the organization's team tools repository.
Publishing is a long-running operation (typically 1-5 minutes). Adjust client timeouts accordingly.
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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 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.
The new version of the tool.
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.
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: 43
{
"project_path": "text",
"bump_type": "major"
}{
"new_version": "text"
}List Tool Versions
Common filters:
deprecated=true|falseversions=<pep440 constraint>(for example,">=1.2,<2")creator=<org_id,user_id>(repeatable)sort_by=+created_at|-created_at|+version.major|...|+deprecated|-deprecated(repeatable)limit(0-50, default 50),continuation_token(int)
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the tool to retrieve versions for.
^[a-f0-9]{24}$Whether to filter by deprecated tool versions.
A semver constraint that specifies the versions to retrieve.
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.
Whether there are more tool versions to retrieve.
A token to supply to the next request to retrieve the next page of tool versions. Only populated if has_more is True.
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": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"tool_id": "text",
"version": {
"major": 1,
"minor": 1,
"patch": 1
},
"required_envvars": [
"text"
],
"required_secret_envvars": [
"text"
],
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"tool_commit_hash": "text",
"amigo_scaffold_commit_hash": "text",
"project_directory": "text",
"lambda_version": 1,
"creator": {
"user_id": "text",
"user_org_id": "text"
},
"updated_by": {
"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"
}
]
}
}Invoke a Tool Version
Execute a tool version with up to 10 inputs in parallel. Each invocation returns the output and execution duration, or an error if the invocation fails.
Invoke a specified tool version with the given input parameters.
Permissions
This endpoint requires the following permissions:
Tool:InvokeToolfor the tool to invoke.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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: 227
{
"inputs": [
{
"input_parameters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"invocation_mode": "regular",
"nonsensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"sensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}{
"invocation_results": [
{
"succeeded": true,
"output": "text",
"duration_ms": 1
}
]
}Get Tool Invocations
Retrieve historical tool invocations across conversations and simulations. All invocations are recorded regardless of success or rollback status.
Common filters:
tool_id=<tool_id>version=<pep440 constraint>(for example,">=1.2,<2")invocation_source_type=regular-conversation|simulation-conversationconversation_id=<id>succeeded=true|false
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The IDs of the tools to get invocations for.
[]A list of semver constraints that specifies the versions 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 IDs associated with the invocations if they are of invocation source regular-conversation.
[]The simulation unit test set run IDs associated with the invocations if they are of invocation source simulation-conversation.
[]Whether the invocation succeeded.
The maximum number of tool invocations to retrieve.
100The token from the previous request to return the next page of tool invocations.
0The fields to sort the sets 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.
Whether there are more tool invocations to retrieve.
The continuation token to retrieve the next page of tool invocations, or null if there are no more tool invocations.
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": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"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
}
},
"duration_ms": 1,
"tool_id": "text",
"tool_version": {
"major": 1,
"minor": 1,
"patch": 1
},
"inputs": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"has_more": true,
"continuation_token": null
}Search Tool Invocations
Search tool invocations by text query across outputs, error messages, and stack traces.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The search query.
The IDs of the tools 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": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"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
}
},
"duration_ms": 1,
"tool_id": "text",
"tool_version": {
"major": 1,
"minor": 1,
"patch": 1
},
"inputs": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}Deprecate Tool Versions
Remove specific tool versions from production use.
Notes:
versionsis a semantic version constraint (PEP 440 style), for example>=1.0,<2.Response: 204 No Content
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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
Deprecate a Tool
Behavior:
Marks the tool and all its versions as deprecated; the tool is no longer used.
Propagation across the system can take about a minute.
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 username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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
Tool Scaffold Setup (CLI)
The forge tool-scaffold install command automates installation of the amigo_tool_scaffold package into your tool directories, handling authentication and package manager configuration in a single step.
--env / -e
Yes
Environment name
--tool / -t
No
Install in a specific tool directory
--all
No
Install in all tool directories
--verbose / -v
No
Enable verbose output
Download Tool Scaffold
Download the latest tool scaffold release as a .tar.gz archive. The scaffold provides the base project structure for building new tools.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
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.
Specified organization is not found.
Invalid request path 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/amigo_tool_scaffold.tar.gz HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
textRelated
Getting Started → Authentication
Getting Started → Regions & Endpoints
Classic API -> Services
Best Practices → Version Sets & Promotion
Last updated
Was this helpful?