Retrieve all API tool definitions registered in HandsAI.
This endpoint returns a flat list of all tools, including their parameters and provider information.
Request curl -X GET "http://localhost:8080/admin/tools/api" \ -H "Authorization: Bearer YOUR_TOKEN"
Response Returns an array of ApiToolResponse objects:
Unique identifier for the tool
Unique code identifier for the tool (used in MCP protocol)
Detailed description of what the tool does
ID of the associated API provider
Name of the associated API provider
Relative path to append to the provider’s base URL
HTTP method for the endpoint. Possible values:
GETPOSTPUTDELETEPATCHHEADOPTIONSTRACE Whether the tool is currently enabled for use
Health status of the tool endpoint
Timestamp of the last health check (ISO-8601 format)
Whether this tool can be exported to external systems
Array of tool parameter definitions Show ToolParameterResponse properties
Unique identifier for the parameter
Parameter code identifier
Data type of the parameter. Possible values:
STRINGNUMBERBOOLEANOBJECTARRAY Description of the parameter’s purpose
Whether this parameter is required
Default value if not provided
Example Response [ { "id" : 1 , "code" : "github_create_issue" , "name" : "Create GitHub Issue" , "description" : "Creates a new issue in a GitHub repository" , "providerId" : 5 , "providerName" : "GitHub API" , "endpointPath" : "/repos/{owner}/{repo}/issues" , "httpMethod" : "POST" , "enabled" : true , "healthy" : true , "lastHealthCheck" : "2026-03-03T10:30:00Z" , "isExportable" : true , "parameters" : [ { "id" : 10 , "code" : "owner" , "name" : "Repository Owner" , "type" : "STRING" , "description" : "GitHub username or organization" , "required" : true , "defaultValue" : null }, { "id" : 11 , "code" : "repo" , "name" : "Repository Name" , "type" : "STRING" , "description" : "Name of the repository" , "required" : true , "defaultValue" : null }, { "id" : 12 , "code" : "title" , "name" : "Issue Title" , "type" : "STRING" , "description" : "Title of the issue" , "required" : true , "defaultValue" : null } ] } ]
Retrieve a specific tool by its unique identifier.
Request curl -X GET "http://localhost:8080/admin/tools/api/1" \ -H "Authorization: Bearer YOUR_TOKEN"
Path Parameters Unique identifier of the tool to retrieve
Response Returns a single ApiToolResponse object with all fields described in the List All Tools section.
Example Response { "id" : 1 , "code" : "github_create_issue" , "name" : "Create GitHub Issue" , "description" : "Creates a new issue in a GitHub repository" , "providerId" : 5 , "providerName" : "GitHub API" , "endpointPath" : "/repos/{owner}/{repo}/issues" , "httpMethod" : "POST" , "enabled" : true , "healthy" : true , "lastHealthCheck" : "2026-03-03T10:30:00Z" , "isExportable" : true , "parameters" : [ { "id" : 10 , "code" : "owner" , "name" : "Repository Owner" , "type" : "STRING" , "description" : "GitHub username or organization" , "required" : true , "defaultValue" : null } ] }
Create a new API tool definition.
Request curl -X POST "http://localhost:8080/admin/tools/api" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Create GitHub Issue", "code": "github_create_issue", "enabled": true, "description": "Creates a new issue in a GitHub repository", "providerId": 5, "endpointPath": "/repos/{owner}/{repo}/issues", "httpMethod": "POST", "isExportable": true, "parameters": [ { "name": "owner", "type": "STRING", "description": "GitHub username or organization", "required": true, "defaultValue": null }, { "name": "repo", "type": "STRING", "description": "Name of the repository", "required": true, "defaultValue": null }, { "name": "title", "type": "STRING", "description": "Title of the issue", "required": true, "defaultValue": null } ] }'
Request Body Unique code identifier for the tool
Whether the tool should be enabled immediately (defaults to true)
Detailed description of what the tool does
ID of the API provider to use for this tool
Relative endpoint path (appended to provider’s baseUrl)
HTTP method for the endpoint (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE)
Whether this tool can be exported to external systems
Array of parameter definitions for this tool Show ToolParameterRequest properties
Data type (STRING, NUMBER, BOOLEAN, OBJECT, ARRAY)
Description of the parameter
Whether this parameter is required
Default value if not provided
Response Returns an ApiResponse object:
HTTP status code (200 for success)
Example Response { "status" : 200 , "message" : "Tool creada correctamente" }
Create multiple API tools in a single request for efficient bulk registration.
Request curl -X POST "http://localhost:8080/admin/tools/api/batch" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "name": "GitHub Create Issue", "code": "github_create_issue", "enabled": true, "description": "Creates a new issue in a GitHub repository", "providerId": 5, "endpointPath": "/repos/{owner}/{repo}/issues", "httpMethod": "POST", "parameters": [ { "name": "owner", "type": "STRING", "description": "Repository owner", "required": true }, { "name": "repo", "type": "STRING", "description": "Repository name", "required": true }, { "name": "title", "type": "STRING", "description": "Issue title", "required": true }, { "name": "body", "type": "STRING", "description": "Issue description", "required": false } ] }, { "name": "GitHub List PRs", "code": "github_list_prs", "enabled": true, "description": "List pull requests in a repository", "providerId": 5, "endpointPath": "/repos/{owner}/{repo}/pulls", "httpMethod": "GET", "parameters": [ { "name": "owner", "type": "STRING", "description": "Repository owner", "required": true }, { "name": "repo", "type": "STRING", "description": "Repository name", "required": true } ] } ]'
Request Body Array of CreateApiToolRequest objects (same structure as single tool creation).
Response HTTP status code (200 for success)
Success message indicating the number of tools created
Example Response { "status" : 200 , "message" : "2 tools creadas correctamente" }
Use batch creation when importing multiple tools from a provider. This is more efficient than creating tools one-by-one and reduces database transactions.
The batch endpoint is particularly useful when paired with the Import/Export API for migrating tool configurations between environments.
Update an existing API tool definition.
Request curl -X PUT "http://localhost:8080/admin/tools/api/1" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Create GitHub Issue (Updated)", "code": "github_create_issue", "enabled": true, "description": "Creates a new issue in a GitHub repository with labels", "providerId": 5, "endpointPath": "/repos/{owner}/{repo}/issues", "httpMethod": "POST", "isExportable": true, "parameters": [ { "name": "owner", "type": "STRING", "description": "GitHub username or organization", "required": true, "defaultValue": null }, { "name": "repo", "type": "STRING", "description": "Name of the repository", "required": true, "defaultValue": null }, { "name": "title", "type": "STRING", "description": "Title of the issue", "required": true, "defaultValue": null }, { "name": "labels", "type": "ARRAY", "description": "Labels to apply to the issue", "required": false, "defaultValue": null } ] }'
Path Parameters Unique identifier of the tool to update
Request Body Same as Create Tool request body.
Response Returns the updated ApiToolResponse object with all fields.
Delete an API tool definition.
Request curl -X DELETE "http://localhost:8080/admin/tools/api/1" \ -H "Authorization: Bearer YOUR_TOKEN"
Path Parameters Unique identifier of the tool to delete
Response Returns HTTP 204 No Content on successful deletion.
Deleting a tool is permanent and cannot be undone. Any references to this tool will become invalid.
Validate the health of a tool’s endpoint by making a test request.
Request curl -X POST "http://localhost:8080/admin/tools/api/1/validate" \ -H "Authorization: Bearer YOUR_TOKEN"
Path Parameters Unique identifier of the tool to validate
Response Returns the updated ApiToolResponse object with refreshed healthy and lastHealthCheck fields.
The health check performs an actual request to the tool’s endpoint to verify it’s accessible and responding correctly.