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.

  • Tool output visibility is controlled by the result_persistence property 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 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.

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.

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)

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 Modes

The result_persistence property can take three values:

Value
Behavior
Use Case

"ephemeral"

Tool result is visible only during the current LLM interaction (e.g., parameter generation, action selection) and is not persisted in the conversation log for future interactions.

Large outputs only needed for immediate decision-making; temporary processing results; intermediate computation steps that don't require long-term context.

"persisted-preferred"

Tool result is persisted in all future interaction logs if output is less than 5k characters. Outputs exceeding 5k characters are automatically treated as ephemeral and excluded from future logs.

Most general-purpose tools where results should be available to the agent when possible, with graceful handling of unexpectedly large outputs.

"persisted"

Tool result is persisted in all future interaction logs if output is less than 5k characters. Outputs exceeding 5k characters cause the tool invocation to throw an error.

Critical tools whose outputs must always be available to the agent; tools designed never to produce large outputs (e.g., status lookups, account queries).

Important Limits

  • Individual tool outputs have a 20k character limit (enforced during tool execution)

  • Persistence thresholds are 5k characters (for "persisted" and "persisted-preferred" modes)

Configuration

The result_persistence property is configured within tool call specifications in your Context Graph state definitions (API: service_hierarchical_state_machine). Different state types support tool call specs in different contexts:

State Type
Field
Description

ActionState

action_tool_call_specs[].result_persistence

Tools used during action execution

ActionState

exit_condition_tool_call_specs[].result_persistence

Tools used when evaluating exit conditions

DecisionState

tool_call_specs[].result_persistence

Helper tools during decision-making

ReflectionState

tool_call_specs[].result_persistence

Helper tools during reflection generation

ToolCallState

tool_call_specs[].result_persistence

Helper tools during designated tool parameter generation

Example Configuration

{
  "type": "action",
  "name": "customer_support",
  "action_tool_call_specs": [
    {
      "tool_id": "670a1234567890abcdef1234",
      "version_constraint": ">=1.0.0",
      "additional_instruction": "Search the knowledge base for relevant articles",
      "audio_fillers": ["Let me search for that..."],
      "audio_filler_triggered_after": 2.0,
      "result_persistence": "persisted-preferred"
    }
  ]
}

Best Practices

  1. Prefer "persisted-preferred" for most tools: Provides the best balance between context availability and graceful handling of large outputs.

  2. 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 maintain efficient agent performance.

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

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

post
/v1/{organization}/tool/

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
post
/v1/{organization}/tool/
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
/v1/{organization}/tool/
Authorizations
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

Path parameters
organizationstringRequired
Query parameters
idstring[]Optional

The IDs of the tools 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 · 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
/v1/{organization}/tool/
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-12-03T05:34:10.220Z",
      "updated_at": "2025-12-03T05:34:10.220Z",
      "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
/v1/{organization}/tool/{tool_id}

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
post
/v1/{organization}/tool/{tool_id}
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
/v1/{organization}/tool/{tool_id}/envvar

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
post
/v1/{organization}/tool/{tool_id}/envvar
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 inputs must include both input_parameters and invocation_mode (typically "regular" for testing production behavior or "conversation-simulation" for testing simulation behavior).

Test a tool

post
/v1/{organization}/tool/test
Authorizations
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
/v1/{organization}/tool/test
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
/v1/{organization}/tool/{tool_id}/version

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
post
/v1/{organization}/tool/{tool_id}/version
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
/v1/{organization}/tool/{tool_id}/version
Authorizations
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

Path parameters
organizationstringRequired
tool_idstringRequired

The ID of the tool to retrieve versions for.

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

Whether to filter by deprecated tool versions.

booleanOptional
or
nullOptional
versionsany ofOptional

A semver constraint that specifies the versions to retrieve.

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
/v1/{organization}/tool/{tool_id}/version
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-12-03T05:34:10.220Z",
      "updated_at": "2025-12-03T05:34:10.220Z",
      "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.

Each input must include:

  • input_parameters: An object containing the parameters expected by your tool

  • invocation_mode: Either "regular" (for production use) or "conversation-simulation" (for testing)

See Execution Modes for details on how to implement mode-specific behavior.

Invoke a tool version

post
/v1/{organization}/tool/{tool_id}/version/{version}/invoke

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
/v1/{organization}/tool/{tool_id}/version/{version}/invoke
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
/v1/{organization}/tool/invocation

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

Path parameters
organizationstringRequired
Query parameters
tool_idstring[]Optional

The IDs of the tools to get invocations for.

Default: []
versionstring[]Optional

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.

Default: []
conversation_idstring[]Optional

The conversation IDs associated with the invocations if they are of invocation source regular-conversation.

Default: []
simulation_unit_test_set_run_idstring[]Optional

The simulation unit test set run IDs associated with the invocations if they are 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 retrieve.

Default: 100
continuation_tokenintegerOptional

The token from the previous request to return the next page of tool invocations.

Default: 0
sort_bystring[]Optional

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

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
/v1/{organization}/tool/invocation
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-12-03T05:34:10.220Z",
      "updated_at": "2025-12-03T05:34:10.220Z",
      "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
/v1/{organization}/tool/invocation/search
Authorizations
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

Path parameters
organizationstringRequired
Query parameters
querystringRequired

The search query.

tool_idstring[]Optional

The IDs of the tools 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
/v1/{organization}/tool/invocation/search
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-12-03T05:34:10.220Z",
      "updated_at": "2025-12-03T05:34:10.220Z",
      "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
/v1/{organization}/tool/{tool_id}/version/{versions}

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
delete
/v1/{organization}/tool/{tool_id}/version/{versions}
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
/v1/{organization}/tool/{tool_id}

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
AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

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.

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
delete
/v1/{organization}/tool/{tool_id}
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?