Version: v5.2

Tools

Overview

The Tools API allows you to list, create, update, retrieve, and delete tools.

With this REST API, you can do the following:

List tools
Create tool
Get tool by ID
Update tool by ID
Delete tool by ID

List tools

Endpoints

GET aisvc/api/v1/tools

Request

Query parameters

Parameter	Type	Description	Required
`_offset`	Integer	Number of results to skip	Optional
`_pageSize`	Integer	Number of results per page	Optional
`_userType`	String	Filter by the tool's unique identifier (`_userType`)	Optional
`_type`	String	Filter by the tool type (`user_tool` or `system_tool`)	Optional
`query`	String	Wildcard search on the name and description of tools	Optional

Request example

None

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

{
  "_list": [
    {
      "_name": "AggregateReadingsTool",
      "_description": "Helps to execute an aggregation query on Reading objects.",
      "_userType": "AggregateReadingsTool",
      "_namespaces": [
        "default"
      ],
      "_id": "77b7f4db-c8e7-40a2-bac0-9e964c5620e9",
      "_type": "system_tool",
      "_irn": "aisvc:tool:77b7f4db-c8e7-40a2-bac0-9e964c5620e9",
      "_metadata": {}
    },
    {
      "_name": "Get Assets Tool",
      "_description": "Get assets",
      "_userType": "GetAssetsTool",
      "_namespaces": [
        "autotesting1_leT0AMOg"
      ],
      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_type": "user_tool",
      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_metadata": {
        "_createdAt": "1757178319536",
        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_updatedAt": "1757178319536"
      }
    }
  ],
  "_offset": 0,
  "_pageSize": 25,
  "_total": 50
}

Create tool

Endpoints

POST aisvc/api/v1/tools

Request

Request body

Parameter	Type	Description	Required
`_namespaces`	Array of String	The namespace(s) of the tool resource	Required
`_name`	String	The tool name	Required
`_description`	String	A short description of what the tool does	Optional
`_userType`	String	Unique identifier of the tool	Required

Request body example

[
  {
    "_name": "Get Assets Tool",
    "_description": "Get assets",
    "_userType": "GetAssetsTool",
    "_namespaces": [
      "autotesting1_leT0AMOg"
    ]
  }
]

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

{
  "_offset": 0,
  "_pageSize": 1,
  "_total": 1,
  "_list": [
    {
      "_name": "Get Assets Tool",
      "_description": "Get sasets",
      "_userType": "GetAssetsTool",
      "_namespaces": [
        "autotesting1_leT0AMOg"
      ],
      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_type": "user_tool",
      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_metadata": {
        "_createdAt": "1757178319536",
        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_updatedAt": "1757178319536"
      }
    }
  ]
}

Get tool by ID

Endpoints

GET aisvc/api/v1/tools/{id}

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

    {
      "_name": "Get Assets Tool",
      "_description": "Get assets",
      "_userType": "GetAssetsTool",
      "_namespaces": [
        "autotesting1_leT0AMOg"
      ],
      "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_type": "user_tool",
      "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",
      "_metadata": {
        "_createdAt": "1757178319536",
        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
        "_updatedAt": "1757178319536"
      }
    }

Update tool by ID

Endpoints

PUT aisvc/api/v1/tools/{id}

Request

Request body

Parameter	Type	Description	Required
`_name`	String	The tool name	Required
`_description`	String	A short description of what the tool does	Optional
`_userType`	String	Unique identifier of the tool	Required

Request body example

    {
      "_name": "Get Assets Tool",
      "_description": "Get assets",
      "_userType": "GetAssetsTool",
      "_namespaces": [
        "autotesting1_leT0AMOg"
      ]
    }

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

{
  "_name": "Get Assets Tool",
  "_description": "Get assets",
  "_userType": "GetAssetsTool",
  "_namespaces": [
    "autotesting1_leT0AMOg"
  ],
  "_id": "6b2991be-7d9f-4203-8578-b8e9545f1700",
  "_type": "user_tool",
  "_irn": "aisvc:tool:6b2991be-7d9f-4203-8578-b8e9545f1700",
  "_metadata": {
    "_createdAt": "1757178319536",
    "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
    "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",
    "_updatedAt": "1757178319536"
  }
}

Delete tool by ID

Endpoints

DELETE aisvc/api/v1/tools/{id}

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

// empty response body

<!-- Hidden per PLN-2761: custom tools run in the AI Service process space and are no longer documented. Use custom MCP tools instead.

Upload Tool Source Code

Endpoints

PUT aisvc/api/v1/tools/{id}/sourcecodes

Request

Request body

{
    "_content":"import { AbstractTool } from '@dtplatform/agent-core';\nimport * as PlatformAPI from '@dtplatform/platform-api';\nconst { IafItemSvc } = PlatformAPI;\nimport { z } from 'zod';\n\nconst toolSchema = z.object({\n  name: z.string().optional().nullable().describe('Filter by asset name. Supports regex'),\n  dtCategory: z.string().optional().nullable().describe('Filter by the dtCategory property. Supports regex'),\n  dtType: z.string().optional().nullable().describe('Filter by dtType property. Supports regex'),\n  _pageSize: z.string().optional().nullable().describe('Sets the number of results to return per Page in the response'),\n  _offset: z.string().optional().nullable().describe('Sets the number of results to skip in the Page response. For example, set to `10` to skip the first 10 results.')\n});\n\nexport default class GetAssetsTool extends AbstractTool {\n  name: string = 'GetAssetsTool';\n  description: string = 'Helps to retrieve Assets based on the provided criteria.';\n  requestContext: any = {};\n  schema: any = toolSchema;\n\n  constructor(...args: any[]) {\n    super(...args);\n    const [{ requestContext }] = args;\n    this.requestContext = requestContext;\n  }\n\n  async _call(args: z.infer<typeof toolSchema>) {\n    let criteria: any = { '$or': [] };\n    let options: any = {};\n    let response: any = {};\n\n    if (args.name || args.dtCategory || args.dtType) {\n      if (args.name) {\n        criteria['$or'].push({\n          'Asset Name': {\n            '$regex': this.toRegexString(args.name),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtCategory) {\n        criteria['$or'].push({\n          'properties.dtCategory.val': {\n            '$regex': this.toRegexString(args.dtCategory),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtType) {\n        criteria['$or'].push({\n          'properties.dtType.val': {\n            '$regex': this.toRegexString(args.dtType),\n            '$options': 'i'\n          }\n        });\n      }\n\n      if (args._pageSize) {\n        options['_pageSize'] = parseInt(args._pageSize, 10);\n      }\n      if (args._offset) {\n        options['_offset'] = parseInt(args._offset, 10);\n      }\n\n      let colQuery = {\n        query: {\n          _userType: 'iaf_ext_asset_coll',\n          _itemClass: 'NamedUserCollection'\n        }\n      };\n\n      const colOptions = {\n        project: { _userType: 1, _itemClass: 1 },\n        sort: { _name: 1 },\n        page: { _offset: 0, _pageSize: 1 }\n      };\n\n      const colResponse = await IafItemSvc.getNamedUserItems(\n        colQuery,\n        this.requestContext,\n        colOptions\n      );\n\n\n\n      let assetCollection: any = null;\n      if (colResponse && Array.isArray(colResponse._list) && colResponse._list.length > 0) {\n        assetCollection = colResponse._list[0];\n        if (assetCollection && assetCollection._id) {\n          response = await IafItemSvc.getRelatedItems(\n            assetCollection._id,\n            {query: criteria},\n            this.requestContext,\n            options            \n          );\n        }\n      }\n    }\n    return response;\n  }\n\n  toRegexString(str) {\n    const quoted = str.match(/^'(.*)'$/);\n    if (quoted) {\n      const escaped = quoted[1].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');\n      return `.*(${escaped}).*`;\n    }\n    const terms = str\n      .split(/\s+/)\n      .map(term => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));\n    return `.*(${terms.join('|')}).*`;\n  }\n}\n"
}

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Get Tool Source Code

Endpoints

GET aisvc/api/v1/tools/{id}/sourcecodes

Response

Codes

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response body

    [
    {
        "_content": "import { AbstractTool } from '@dtplatform/agent-core';\nimport * as PlatformAPI from '@dtplatform/platform-api';\nconst { IafItemSvc } = PlatformAPI;\nimport { z } from 'zod';\n\nconst toolSchema = z.object({\n  name: z.string().optional().nullable().describe('Filter by asset name. Supports regex'),\n  dtCategory: z.string().optional().nullable().describe('Filter by the dtCategory property. Supports regex'),\n  dtType: z.string().optional().nullable().describe('Filter by dtType property. Supports regex'),\n  _pageSize: z.string().optional().nullable().describe('Sets the number of results to return per Page in the response'),\n  _offset: z.string().optional().nullable().describe('Sets the number of results to skip in the Page response. For example, set to `10` to skip the first 10 results.')\n});\n\nexport default class GetAssetsTool extends AbstractTool {\n  name: string = 'GetAssetsTool';\n  description: string = 'Helps to retrieve Assets based on the provided criteria.';\n  requestContext: any = {};\n  schema: any = toolSchema;\n\n  constructor(...args: any[]) {\n    super(...args);\n    const [{ requestContext }] = args;\n    this.requestContext = requestContext;\n  }\n\n  async _call(args: z.infer<typeof toolSchema>) {\n    let criteria: any = { '$or': [] };\n    let options: any = {};\n    let response: any = {};\n\n    if (args.name || args.dtCategory || args.dtType) {\n      if (args.name) {\n        criteria['$or'].push({\n          'Asset Name': {\n            '$regex': this.toRegexString(args.name),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtCategory) {\n        criteria['$or'].push({\n          'properties.dtCategory.val': {\n            '$regex': this.toRegexString(args.dtCategory),\n            '$options': 'i'\n          }\n        });\n      }\n      if (args.dtType) {\n        criteria['$or'].push({\n          'properties.dtType.val': {\n            '$regex': this.toRegexString(args.dtType),\n            '$options': 'i'\n          }\n        });\n      }\n\n      if (args._pageSize) {\n        options['_pageSize'] = parseInt(args._pageSize, 10);\n      }\n      if (args._offset) {\n        options['_offset'] = parseInt(args._offset, 10);\n      }\n\n      let colQuery = {\n        query: {\n          _userType: 'iaf_ext_asset_coll',\n          _itemClass: 'NamedUserCollection'\n        }\n      };\n\n      const colOptions = {\n        project: { _userType: 1, _itemClass: 1 },\n        sort: { _name: 1 },\n        page: { _offset: 0, _pageSize: 1 }\n      };\n\n      const colResponse = await IafItemSvc.getNamedUserItems(\n        colQuery,\n        this.requestContext,\n        colOptions\n      );\n\n\n\n      let assetCollection: any = null;\n      if (colResponse && Array.isArray(colResponse._list) && colResponse._list.length > 0) {\n        assetCollection = colResponse._list[0];\n        if (assetCollection && assetCollection._id) {\n          response = await IafItemSvc.getRelatedItems(\n            assetCollection._id,\n            {query: criteria},\n            this.requestContext,\n            options            \n          );\n        }\n      }\n    }\n    return response;\n  }\n\n  toRegexString(str) {\n    const quoted = str.match(/^'(.*)'$/);\n    if (quoted) {\n      const escaped = quoted[1].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');\n      return `.*(${escaped}).*`;\n    }\n    const terms = str\n      .split(/\s+/)\n      .map(term => term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));\n    return `.*(${terms.join('|')}).*`;\n  }\n}\n"
    }
]

-->

Overview​

List tools​

Endpoints​

Request​

Query parameters​

Request example​

Response​

Codes​

Response body​

Create tool​

Endpoints​

Request​

Request body​

Request body example​

Response​

Codes​

Response body​

Get tool by ID​

Endpoints​

Response​

Codes​

Response body​

Update tool by ID​

Endpoints​

Request​

Request body​

Request body example​

Response​

Codes​

Response body​

Delete tool by ID​

Endpoints​

Response​

Codes​

Response body​

Upload Tool Source Code​

Endpoints​

Request​

Request body​

Response​

Codes​

Get Tool Source Code​

Endpoints​

Response​

Codes​

Response body​

Overview

List tools

Endpoints

Request

Query parameters

Request example

Response

Codes

Response body

Create tool

Endpoints

Request

Request body

Request body example

Response

Codes

Response body

Get tool by ID

Endpoints

Response

Codes

Response body

Update tool by ID

Endpoints

Request

Request body

Request body example

Response

Codes

Response body

Delete tool by ID

Endpoints

Response

Codes

Response body

Upload Tool Source Code

Endpoints

Request

Request body

Response

Codes

Get Tool Source Code

Endpoints

Response

Codes

Response body