Tools
Overview#
The Tools API allows you to list, create, update, retrieve, and delete tools. You can also use it to upload and retrieve source code for 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
- Upload tool source code
- Get tool source code
List tools#
Endpoints#
GET aisvc/api/v1/toolsRequest#
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", "_toolClass": "GetAssetsTool", "_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/toolsRequest#
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 |
_toolClass | String | Class name of the custom tool implementation | Optional |
Request body example#
[ { "_name": "Get Assets Tool", "_description": "Get assets", "_userType": "GetAssetsTool", "_namespaces": [ "autotesting1_leT0AMOg" ], "_toolClass": "GetAssetsTool" }]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", "_toolClass": "GetAssetsTool", "_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", "_toolClass": "GetAssetsTool", "_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 |
_toolClass | String | Class name of the custom tool implementation | Optional |
Request body example#
{ "_name": "Get Assets Tool", "_description": "Get assets", "_userType": "GetAssetsTool", "_namespaces": [ "autotesting1_leT0AMOg" ], "_toolClass": "GetAssetsTool", }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", "_toolClass": "GetAssetsTool", "_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 bodyUpload Tool Source Code#
Endpoints#
PUT aisvc/api/v1/tools/{id}/sourcecodesRequest#
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}/sourcecodesResponse#
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" }]