Tool Instances

List Tool Instances

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

Query Parameters

tool_id?|

Filter by tool ID

active_only?Active Only

Only active instances

Defaultfalse

limit?Limit

Maximum number of items to return (1-200)

Default50

Range1 <= value <= 200

cursor?|

Cursor for pagination (from previous response's next_cursor)

Header Parameters

x-trace-id?string|null

authorization?string|null

Response Body

`application/json`

curl -X GET "https://loading/v1/orgs/string/workspaces/string/tool-instances"

{
  "total": 0,
  "has_more": false,
  "next_cursor": "string",
  "instances": [
    {
      "instance_id": "string",
      "tool_id": "string",
      "workspace_id": "string",
      "namespace_id": "string",
      "name": "string",
      "description": "string",
      "configuration": {},
      "has_credentials": true,
      "credential_refs": {
        "property1": "string",
        "property2": "string"
      },
      "credential_fields": [
        "string"
      ],
      "custom_action_parameters": {
        "property1": [
          {}
        ],
        "property2": [
          {}
        ]
      },
      "action_defaults": {
        "property1": {},
        "property2": {}
      },
      "auth_config": {},
      "custom_actions": [
        {}
      ],
      "is_active": true,
      "mcp_description_override": "string",
      "mcp_action_filter": [
        "string"
      ],
      "mcp_action_descriptions": {
        "property1": "string",
        "property2": "string"
      },
      "mcp_max_calls_per_turn": 0,
      "mcp_requires_confirmation": false,
      "mcp_parameter_overrides": {
        "property1": {
          "property1": {},
          "property2": {}
        },
        "property2": {
          "property1": {},
          "property2": {}
        }
      },
      "auth_mode": "vault",
      "connection_credentials": {
        "client_id": "string",
        "client_secret_vault_id": "string",
        "callback_url": "string",
        "scopes_override": [
          "string"
        ]
      },
      "connection_status": "string",
      "schema_version": 1,
      "upgrade_available": false,
      "latest_schema_version": 0,
      "schema_deprecated": false,
      "last_used_at": "string",
      "usage_count": 0,
      "created_by": "string",
      "created_at": "string",
      "updated_at": "string",
      "tool_name": "string",
      "tool_slug": "string",
      "tool_category": "string",
      "tool_icon_url": "string",
      "supported_step_types": [
        "string"
      ],
      "effective_action_schemas": [
        {}
      ],
      "tool_config_schema": [
        {
          "name": "string",
          "display_name": "string",
          "type": "string",
          "required": false,
          "default": null,
          "description": "string",
          "placeholder": "string",
          "options": [
            {
              "property1": "string",
              "property2": "string"
            }
          ],
          "validation": {},
          "widget": "string",
          "widget_options": {}
        }
      ]
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Create Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tool_id*Tool Id

ID of the tool from library

name*Name

Length1 <= length <= 100

description?|null

namespace_id?|

DEPRECATED — namespace-level credential scoping is handled by credential_templates on steps. Kept for backward compatibility.

auth_mode?Auth Mode

Authentication mode: 'vault' (provide credential_refs) or 'connection' (managed OAuth/API key via namespace connections). Only tools with connection_config support 'connection' mode.

Default"vault"

configuration?

credential_refs?

Map of credential field names to vault secret IDs. Required when auth_mode is 'vault', ignored when 'connection'.

connection_credentials?|

OAuth app credentials for managed connection mode. Contains client_id, client_secret_vault_id, callback_url.

custom_action_parameters?

Custom parameters per action to extend base schema

action_defaults?

Default values for action parameters

auth_config?|

Authentication configuration for Custom REST tool

custom_actions?array<>

User-defined REST actions for Custom REST tool

is_active?Is Active

Defaulttrue

mcp_description_override?|null

mcp_action_filter?array<string>|null

mcp_action_descriptions?|null

mcp_max_calls_per_turn?|null

mcp_requires_confirmation?Mcp Requires Confirmation

Defaultfalse

mcp_parameter_overrides?|null

Response Body

`application/json`

curl -X POST "https://loading/v1/orgs/string/workspaces/string/tool-instances" \  -H "Content-Type: application/json" \  -d '{    "tool_id": "string",    "name": "string"  }'

{
  "instance_id": "string",
  "tool_id": "string",
  "workspace_id": "string",
  "namespace_id": "string",
  "name": "string",
  "description": "string",
  "configuration": {},
  "has_credentials": true,
  "credential_refs": {
    "property1": "string",
    "property2": "string"
  },
  "credential_fields": [
    "string"
  ],
  "custom_action_parameters": {
    "property1": [
      {}
    ],
    "property2": [
      {}
    ]
  },
  "action_defaults": {
    "property1": {},
    "property2": {}
  },
  "auth_config": {},
  "custom_actions": [
    {}
  ],
  "is_active": true,
  "mcp_description_override": "string",
  "mcp_action_filter": [
    "string"
  ],
  "mcp_action_descriptions": {
    "property1": "string",
    "property2": "string"
  },
  "mcp_max_calls_per_turn": 0,
  "mcp_requires_confirmation": false,
  "mcp_parameter_overrides": {
    "property1": {
      "property1": {},
      "property2": {}
    },
    "property2": {
      "property1": {},
      "property2": {}
    }
  },
  "auth_mode": "vault",
  "connection_credentials": {
    "client_id": "string",
    "client_secret_vault_id": "string",
    "callback_url": "string",
    "scopes_override": [
      "string"
    ]
  },
  "connection_status": "string",
  "schema_version": 1,
  "upgrade_available": false,
  "latest_schema_version": 0,
  "schema_deprecated": false,
  "last_used_at": "string",
  "usage_count": 0,
  "created_by": "string",
  "created_at": "string",
  "updated_at": "string",
  "tool_name": "string",
  "tool_slug": "string",
  "tool_category": "string",
  "tool_icon_url": "string",
  "supported_step_types": [
    "string"
  ],
  "effective_action_schemas": [
    {}
  ],
  "tool_config_schema": [
    {
      "name": "string",
      "display_name": "string",
      "type": "string",
      "required": false,
      "default": null,
      "description": "string",
      "placeholder": "string",
      "options": [
        {
          "property1": "string",
          "property2": "string"
        }
      ],
      "validation": {},
      "widget": "string",
      "widget_options": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Get Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Response Body

`application/json`

curl -X GET "https://loading/v1/orgs/string/workspaces/string/tool-instances/string"

{
  "instance_id": "string",
  "tool_id": "string",
  "workspace_id": "string",
  "namespace_id": "string",
  "name": "string",
  "description": "string",
  "configuration": {},
  "has_credentials": true,
  "credential_refs": {
    "property1": "string",
    "property2": "string"
  },
  "credential_fields": [
    "string"
  ],
  "custom_action_parameters": {
    "property1": [
      {}
    ],
    "property2": [
      {}
    ]
  },
  "action_defaults": {
    "property1": {},
    "property2": {}
  },
  "auth_config": {},
  "custom_actions": [
    {}
  ],
  "is_active": true,
  "mcp_description_override": "string",
  "mcp_action_filter": [
    "string"
  ],
  "mcp_action_descriptions": {
    "property1": "string",
    "property2": "string"
  },
  "mcp_max_calls_per_turn": 0,
  "mcp_requires_confirmation": false,
  "mcp_parameter_overrides": {
    "property1": {
      "property1": {},
      "property2": {}
    },
    "property2": {
      "property1": {},
      "property2": {}
    }
  },
  "auth_mode": "vault",
  "connection_credentials": {
    "client_id": "string",
    "client_secret_vault_id": "string",
    "callback_url": "string",
    "scopes_override": [
      "string"
    ]
  },
  "connection_status": "string",
  "schema_version": 1,
  "upgrade_available": false,
  "latest_schema_version": 0,
  "schema_deprecated": false,
  "last_used_at": "string",
  "usage_count": 0,
  "created_by": "string",
  "created_at": "string",
  "updated_at": "string",
  "tool_name": "string",
  "tool_slug": "string",
  "tool_category": "string",
  "tool_icon_url": "string",
  "supported_step_types": [
    "string"
  ],
  "effective_action_schemas": [
    {}
  ],
  "tool_config_schema": [
    {
      "name": "string",
      "display_name": "string",
      "type": "string",
      "required": false,
      "default": null,
      "description": "string",
      "placeholder": "string",
      "options": [
        {
          "property1": "string",
          "property2": "string"
        }
      ],
      "validation": {},
      "widget": "string",
      "widget_options": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Delete Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Response Body

`application/json`

curl -X DELETE "https://loading/v1/orgs/string/workspaces/string/tool-instances/string"

Empty

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Update Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?|null

description?|null

configuration?|null

credential_refs?|null

auth_mode?|

Authentication mode: 'vault' or 'connection'

connection_credentials?|

OAuth app credentials for managed connection mode

custom_action_parameters?|null

action_defaults?|null

auth_config?|null

custom_actions?array<>|null

is_active?boolean|null

mcp_description_override?|null

mcp_action_filter?array<string>|null

mcp_action_descriptions?|null

mcp_max_calls_per_turn?|null

mcp_requires_confirmation?boolean|null

mcp_parameter_overrides?|null

Response Body

`application/json`

curl -X PUT "https://loading/v1/orgs/string/workspaces/string/tool-instances/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "instance_id": "string",
  "tool_id": "string",
  "workspace_id": "string",
  "namespace_id": "string",
  "name": "string",
  "description": "string",
  "configuration": {},
  "has_credentials": true,
  "credential_refs": {
    "property1": "string",
    "property2": "string"
  },
  "credential_fields": [
    "string"
  ],
  "custom_action_parameters": {
    "property1": [
      {}
    ],
    "property2": [
      {}
    ]
  },
  "action_defaults": {
    "property1": {},
    "property2": {}
  },
  "auth_config": {},
  "custom_actions": [
    {}
  ],
  "is_active": true,
  "mcp_description_override": "string",
  "mcp_action_filter": [
    "string"
  ],
  "mcp_action_descriptions": {
    "property1": "string",
    "property2": "string"
  },
  "mcp_max_calls_per_turn": 0,
  "mcp_requires_confirmation": false,
  "mcp_parameter_overrides": {
    "property1": {
      "property1": {},
      "property2": {}
    },
    "property2": {
      "property1": {},
      "property2": {}
    }
  },
  "auth_mode": "vault",
  "connection_credentials": {
    "client_id": "string",
    "client_secret_vault_id": "string",
    "callback_url": "string",
    "scopes_override": [
      "string"
    ]
  },
  "connection_status": "string",
  "schema_version": 1,
  "upgrade_available": false,
  "latest_schema_version": 0,
  "schema_deprecated": false,
  "last_used_at": "string",
  "usage_count": 0,
  "created_by": "string",
  "created_at": "string",
  "updated_at": "string",
  "tool_name": "string",
  "tool_slug": "string",
  "tool_category": "string",
  "tool_icon_url": "string",
  "supported_step_types": [
    "string"
  ],
  "effective_action_schemas": [
    {}
  ],
  "tool_config_schema": [
    {
      "name": "string",
      "display_name": "string",
      "type": "string",
      "required": false,
      "default": null,
      "description": "string",
      "placeholder": "string",
      "options": [
        {
          "property1": "string",
          "property2": "string"
        }
      ],
      "validation": {},
      "widget": "string",
      "widget_options": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Test Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

test_credentials?|

Temporary credentials for testing (not saved)

Response Body

`application/json`

curl -X POST "https://loading/v1/orgs/string/workspaces/string/tool-instances/string/test" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "message": "string",
  "details": {},
  "latency_ms": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Toggle Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

`application/json`

curl -X POST "https://loading/v1/orgs/string/workspaces/string/tool-instances/string/toggle?is_active=true"

{
  "instance_id": "string",
  "tool_id": "string",
  "workspace_id": "string",
  "namespace_id": "string",
  "name": "string",
  "description": "string",
  "configuration": {},
  "has_credentials": true,
  "credential_refs": {
    "property1": "string",
    "property2": "string"
  },
  "credential_fields": [
    "string"
  ],
  "custom_action_parameters": {
    "property1": [
      {}
    ],
    "property2": [
      {}
    ]
  },
  "action_defaults": {
    "property1": {},
    "property2": {}
  },
  "auth_config": {},
  "custom_actions": [
    {}
  ],
  "is_active": true,
  "mcp_description_override": "string",
  "mcp_action_filter": [
    "string"
  ],
  "mcp_action_descriptions": {
    "property1": "string",
    "property2": "string"
  },
  "mcp_max_calls_per_turn": 0,
  "mcp_requires_confirmation": false,
  "mcp_parameter_overrides": {
    "property1": {
      "property1": {},
      "property2": {}
    },
    "property2": {
      "property1": {},
      "property2": {}
    }
  },
  "auth_mode": "vault",
  "connection_credentials": {
    "client_id": "string",
    "client_secret_vault_id": "string",
    "callback_url": "string",
    "scopes_override": [
      "string"
    ]
  },
  "connection_status": "string",
  "schema_version": 1,
  "upgrade_available": false,
  "latest_schema_version": 0,
  "schema_deprecated": false,
  "last_used_at": "string",
  "usage_count": 0,
  "created_by": "string",
  "created_at": "string",
  "updated_at": "string",
  "tool_name": "string",
  "tool_slug": "string",
  "tool_category": "string",
  "tool_icon_url": "string",
  "supported_step_types": [
    "string"
  ],
  "effective_action_schemas": [
    {}
  ],
  "tool_config_schema": [
    {
      "name": "string",
      "display_name": "string",
      "type": "string",
      "required": false,
      "default": null,
      "description": "string",
      "placeholder": "string",
      "options": [
        {
          "property1": "string",
          "property2": "string"
        }
      ],
      "validation": {},
      "widget": "string",
      "widget_options": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Upgrade Tool Instance

Path Parameters

org_id*Org Id

workspace_id*Workspace Id

instance_id*Instance Id

Header Parameters

x-trace-id?string|null

authorization?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

target_version?|

Target schema version. If None, upgrades to latest (current_schema_version).

Response Body

`application/json`

curl -X POST "https://loading/v1/orgs/string/workspaces/string/tool-instances/string/upgrade" \  -H "Content-Type: application/json" \  -d '{}'

{
  "instance_id": "string",
  "previous_version": 0,
  "new_version": 0,
  "migration_applied": true,
  "changelog": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

200application/json

422application/json

201application/json

422application/json

200application/json

422application/json

204

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`