Go to website

Tools

Manage organization-scoped, versioned capabilities ("tools"). This page documents the core API endpoints and expected request/response shapes.

API Terminology In the API, these are called "Tools." In our conceptual documentation, we refer to them as "Actions" - the execution layer that transforms agent reasoning into real-world outcomes. See Conceptual Docs: Actions for the architectural perspective.

Tools are organization‑scoped and versioned. Use the OpenAPI embeds below for exact request/response shapes and parameters.

Scope & Behavior

  • All operations are organization‑scoped.

  • Related operations are serialized per tool; concurrent publish/deprecate on the same tool returns HTTP 409.

How Tools Work (Actions)

Tools run as versioned actions. At a high level:

  • Versioned builds: When you publish, the platform builds your tool from your team branch, pins the source commit, 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: Publish 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 & 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.

Typical lifecycle

  1. Create the tool (name, description, tags).

  2. Add required environment variables for the tool.

  3. Test the tool from a branch before publishing.

  4. Publish a version from your team branch (choose major/minor/patch).

  5. Invoke directly or call from your application/SDK.

  6. Query invocation history for debugging and audit.

  7. Iterate by publishing new versions; deprecate older ones when ready.

Workflow (diagram)

Create a Tool

Create a new tool with metadata (name, description, tags).

Create a new tool

post

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.
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
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
namestring · min: 1Required

The name of the tool. It must be unique among all non-deprecated tools in the organization.

Pattern: ^[a-z0-9_]+$
descriptionstring · min: 1Required

A description of the tool.

Responses
201

Succeeded.

application/json
post
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|false

  • tag=key:value (repeatable; value may be * or empty for null)

  • sort_by=+name|-name|+deprecated|-deprecated (repeatable)

  • limit (1–20, default 10), continuation_token (int, default 0)

Get tools

get
Authorizations
Path parameters
organizationstringRequired
Query parameters
idstring[]Optional

The ID of the tool to retrieve.

Default: []
deprecatedany ofOptional

Whether the tools are deprecated.

booleanOptional
or
nullOptional
sort_bystring[]Optional

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

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: []
limitinteger · min: 1 · max: 20Optional

The maximum number of tools to return.

Default: 10
continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of tools.

Default: 0
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
get
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-11T08:10:01.077Z",
      "updated_at": "2025-10-11T08:10:01.077Z",
      "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"
    ]
  }
}

Update a Tool

Update tool metadata (name, description, tags).

Modify a tool

post

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.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to modify

Pattern: ^[a-f0-9]{24}$
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
descriptionany ofOptional

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

string · min: 1Optional
or
nullOptional
tagsany ofOptional

The tags of this tool. Only updates if not-null.

or
nullOptional
Responses
204

Succeeded.

No content
post
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.

Modify the environment variables of a tool

post

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.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to modify

Pattern: ^[a-f0-9]{24}$
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
Responses
204

Succeeded.

No content
post
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.

Test a tool

post
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
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
commit_branchstringRequired

The branch in the tools repo whose tip will be tested.

project_pathstringRequired

The directory in the tools repo that contains the pyproject.toml file corresponding to the tool version to publish.

Pattern: ^[-\w\d_/]+$
Responses
200

Succeeded

application/json
post
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
    }
  ]
}

Publish a Tool Version

Behavior:

  • Computes next semantic version (or 1.0.0 if none), validates, builds, and publishes.

  • Long-running (1–5 minutes). Serialized per tool. Returns 409 if a related operation is in progress.

Repo guidance:

  • repo: "team" publishes from your team's branch (for example, releases/<TEAM>). Use this for all organization-specific tools.

  • repo: "main" is reserved for the scaffold and canonical, shared tools; do not use it for organization-specific publishing.

Publishing is a long‑running operation (typically 1–5 minutes). Adjust client timeouts accordingly.

Publish a new version of a tool

post

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.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to publish

Pattern: ^[a-f0-9]{24}$
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
repostring · enumRequired

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.

Possible values:
project_pathstringRequired

The directory in the tools repo that contains the pyproject.toml file corresponding to the tool version to publish.

Pattern: ^[-\w\d_/]+$
bump_typestring · enumRequired

The type of bump to apply to the version. For initial version of the tool, use major.

Possible values:
Responses
201

Succeeded.

application/json
post
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"
}

List Tool Versions

Common filters:

  • deprecated=true|false

  • version_constraint=<pep440 constraint> (e.g., ">=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)

Get tool versions

get
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to retrieve versions for.

Pattern: ^[a-f0-9]{24}$
Query parameters
deprecatedany ofOptional

Whether the tools are deprecated.

booleanOptional
or
nullOptional
versionsany ofOptional

A semver constraint that specifies the version to retrieve in the Python packaging specification. If not specified, all versions will be retrieved.

stringOptional
or
nullOptional
sort_bystring[]Optional

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

The creators of the tool versions. Each value must be of the format org_id,user_id.

Default: []
limitinteger · max: 50Optional

The maximum number of tool versions to return.

Default: 50
continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of tool versions.

Default: 0
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
get
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-11T08:10:01.077Z",
      "updated_at": "2025-10-11T08:10:01.077Z",
      "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"
      }
    ]
  }
}

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 tool version

post

Invoke a specified tool version with the given input parameters.

Permissions

This endpoint requires the following permissions:

  • Tool:InvokeTool for the tool to invoke.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to invoke

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

The version of the tool to invoke

Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Body
Responses
200

Succeeded

application/json
post
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
    }
  ]
}

Get Tool Invocations

Retrieve historical tool invocations across conversations and simulations. All invocations are recorded regardless of success or rollback status.

When interactions are rolled back, the associated tool invocations remain in history but conversation_id, interaction_id, and simulation_run_id fields are nullified.

Common filters:

  • tool_id=<tool_id>

  • version=<pep440 constraint> (e.g., ">=1.2,<2")

  • invocation_source_type=conversation|simulation

  • conversation_id=<id>

  • succeeded=true|false

Get tool invocations

get

Retrieve tool invocations under the specified filters.

Permissions

This endpoint may require the following permission:

  • Conversation:GetInteractionInsights for ToolInvocations from a regular conversation.
  • Simulation:GetSimulationUnitTestSetRun for ToolInvocations from a simulation conversation.
Authorizations
Path parameters
organizationstringRequired
Query parameters
tool_idstring[]Optional

The ID of the tool to get invocations for.

Default: []
versionstring[]Optional

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.

Default: []
conversation_idstring[]Optional

The conversation ID associated with the invocation if it's of invocation source regular-conversation

Default: []
simulation_unit_test_set_run_idstring[]Optional

The simulation unit test set run ID associated with the invocation if it's of invocation source simulation-conversation

Default: []
succeededany ofOptional

Whether the invocation succeeded

booleanOptional
or
nullOptional
limitinteger · max: 100Optional

The maximum number of tool invocations to return.

Default: 100
continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of tool invocations.

Default: 0
sort_bystring[]Optional

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

Default: []
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
get
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-11T08:10:01.077Z",
      "updated_at": "2025-10-11T08:10:01.077Z",
      "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
}

Search Tool Invocations

Search tool invocations by text query across outputs, error messages, and stack traces.

Search tool invocations

get
Authorizations
Path parameters
organizationstringRequired
Query parameters
querystringRequired

The search query.

tool_idstring[]Optional

The ID of the tool to get invocations for.

Default: []
conversation_idstring[]Optional

The conversation ID associated with the invocation if it's of invocation source regular-conversation

Default: []
simulation_unit_test_set_run_idstring[]Optional

The simulation unit test set run ID associated with the invocation if it's of invocation source simulation-conversation

Default: []
succeededany ofOptional

Whether the invocation succeeded

booleanOptional
or
nullOptional
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
200

Succeeded.

application/json
get
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-11T08:10:01.077Z",
      "updated_at": "2025-10-11T08:10:01.077Z",
      "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
      }
    }
  ]
}

Deprecate Tool Versions

Remove specific tool versions from production use.

Notes:

  • versions is a semantic version constraint (PEP 440 style), e.g., >=1.0,<2.

  • Response: 204 No Content

Cost note Deprecate versions that are no longer referenced in your applications to control storage‑related costs.

Deprecate tool versions

delete

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.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to deprecate.

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

A semver constraint that specifies the version to deprecate in the Python packaging specification. All versions that match this constraint will be deprecated.

Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
204

Succeeded.

No content
delete
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 and removes runtime versions.

  • Propagation across the system can take ~1 minute.

Deprecate a tool

delete

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.
Authorizations
Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to deprecate.

Pattern: ^[a-f0-9]{24}$
Header parameters
x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional
or
nullOptional
Sec-WebSocket-Protocolstring[]OptionalDefault: []
Responses
204

Succeeded.

No content
delete
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

Related

PreviousServicesNextConversations

Last updated

Was this helpful?