Tools API

The Tools API allows you to define, update, list, and delete Tools. These Tools can then be invoked by Agents.

For generic variables needed to use the API, see the API Reference.

Endpoints

Authentication

All endpoints require authentication using one of the following:

• Authorization: Bearer $GEAI_APITOKEN
• Authorization: Bearer $OAuth_accesstoken

For $OAuth_accesstoken, you must also include the header: ProjectId: $GEAI_PROJECT_ID

Some endpoints may require additional headers such as:

• Content-Type: application/json when a body is sent.
• Accept: application/json only when a JSON response body is needed.

POST /tools

Creates a new Tool inside the current Project.

Parameters

Request

• Method: POST
• Path: $BASE_URL/v2/tools

Request Body

{
  "tool": {
    "name": "string",                      // Name of the Tool. Must be compatible with Open API requested format: operationId_HTTPmethod (e.g., checkWeatherUsingGET_get).
    "description": "string",               // Description of the tool's purpose.
    "scope": "string",                     // Tool type: 'api', 'builtin', or 'external'.
    "openApi": "string",                   // URL to the OpenAPI specification for the tool.
    "reportEvents": "string",              // Event reporting level: 'None', 'All', 'Start', 'Finish', or 'Progress'.
    "parameters": [
      {
        "key": "string",                   // Unique identifier for the parameter.
        "description": "string",           // Description of the parameter's purpose.
        "isRequired": boolean,             // Indicates if the parameter is required for tool execution.
        "type": "string",                  // Parameter type: 'config', 'app', or 'context'.
        "value": "string"                  // For context: the context variable name (e.g., 'USER_ID').
      }
      // Additional parameters.
    ]
  }
}

Response

{
  "accessScope": "string",                // Access level for the tool: 'private' or 'public'.
  "description": "string",                // Description of the tool's purpose.
  "id": "string",                         // Unique identifier of the tool (UUID).
  "isDraft": boolean,                     // Indicates if the tool is in draft state.
  "name": "string",                       // Name of the Tool. Must be compatible with Open API requested format: operationId_HTTPmethod (e.g., checkWeatherUsingGET_get).
  "openApi": "string",                    // URL to the OpenAPI specification for the tool.
  "parameters": [
    {
      "description": "string",            // Description of the parameter's purpose.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "key": "string",                    // Unique identifier for the parameter.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'USER_ID').
    }
    // Additional parameters. 
  ]
  "revision": integer,                    // Revision number of the tool.
  "scope": "api",                         // Tool type: 'api', 'builtin', or 'external'. For Tools created via API this must always be "api".
  "status": "string"                      // Status of the tool (e.g., 'active', 'inactive').
}

cURL Sample

curl -X POST "$BASE_URL/v2/tools" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": {
    "name": "UserInfoAPITool",
    "description": "Fetches user-specific information from an external API using context parameters.",
    "scope": "api",
    "openApi": "https://example.com/openapi/userinfo.json",
    "reportEvents": "None",
    "parameters":[
      {
        "key": "userId",
        "description": "The GUID of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_ID"
      },
      {
        "key": "userEmail",
        "description": "The email of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_EMAIL"
      },
      {
        "key": "projectId",
        "description": "The GUID of the project in context.",
        "isRequired": false,
        "type": "context",
        "value": "PROJECT_ID"
      },
      {
        "key": "dateTime",
        "description": "The current date and time at execution.",
        "isRequired": false,
        "type": "context",
        "value": "DATE_TIME"
      },
      {
        "dataType": "String",
        "description": "Configuration that is static, but it is sensitive information. The value is stored in secret-manager",
        "fromSecret": true,
        "isRequired": true,
        "key": "api_token",
        "type": "config",
        "value": "API_TOKEN"
      }
    ]
  }
}'

PUT /tools/{idOrName}/upsert

Creates the Tool if it does not exist; otherwise, it updates its draft version.

Parameters

Request

• Method: PUT
• Path: $BASE_URL/v2/tools/{idOrName}/upsert

Request Body

{
  "tool": {
    "name": "string",                     // Name of the Tool. Must be compatible with Open API requested format: operationId_HTTPmethod (e.g., checkWeatherUsingGET_get). Can be updated when using this method.
    "description": "string",              // Description of the tool's purpose. Can be updated when using this method.
    "scope": "string",                    // Tool type; 'api', 'builtin', or 'external'. For Tools created via API this must always be "api".
    "openApi": "string",                  // URL to the OpenAPI specification for the tool. Can be updated when using this method.
    "reportEvents": "string",             // Event reporting level: 'None', 'All', 'Start', 'Finish', or 'Progress'. Can be updated when using this method.
    "parameters": [
      {
        "key": "string",                  // Unique identifier for the parameter. Can be updated when using this method.
        "description": "string",          // Description of the parameter's purpose. Can be updated when using this method.
        "isRequired": boolean,            // Indicates if the parameter is required for tool execution.
        "type": "string",                 // Parameter type: 'config', 'app', or 'context'.
        "value": "string"                 // For context: the context variable name (e.g., 'USER_ID').
      }
      // Additional parameters.
    ]
  }
}

Response

{
  "accessScope": "string",                // Access scope ("public" or "private").
  "description": "string",                // Description of the Tool.
  "id": "string",                         // Unique identifier for the Tool.
  "isDraft": boolean,                     // Indicates if the Tool is a draft.
  "messages": [
    {
      "description": "string",            // Message description (e.g., validation warning).
      "type": "string"                    // Message type (e.g., "warning", "info").
    }
    // Additional messages.
  ],
  "name": "string",                       // Name of the Tool.
  "parameters": [
    {
      "key": "string",                    // Unique identifier for the parameter. Can be updated when using this method.
      "description": "string",            // Description of the parameter's purpose. Can be updated when using this method.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'USER_ID').
    }
    // Additional parameters. 
  ],
  "revision": integer,                    // Revision number of the Tool.
  "scope": "string",                      // Tool scope (e.g., "builtin", "custom").
  "status": "string"                      // Tool status (e.g., "active", "draft").
}

cURL Sample

curl -X PUT "$BASE_URL/v2/tools/{idOrName}/upsert?automaticPublish=false" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": {
    "name": "UserContextAPI",
    "description": "Updated version of an API that Fetches user-specific information from an external API using context parameters.",
    "scope": "api",
    "openApi": "https://example.com/openapi/userinfo.json",
    "reportEvents": "None",
    "parameters": [
      {
        "key": "userId",
        "description": "The GUID of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_ID"
      },
      {
        "key": "userEmail",
        "description": "The email of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_EMAIL"
      },
      {
        "key": "projectId",
        "description": "The GUID of the project in context.",
        "isRequired": false,
        "type": "context",
        "value": "PROJECT_ID"
      },
      {
        "key": "dateTime",
        "description": "The current date and time at execution.",
        "isRequired": false,
        "type": "context",
        "value": "DATE_TIME"
      },
      {
        "dataType": "String",
        "description": "Configuration that is static, but it is sensitive information. The value is stored in secret-manager",
        "fromSecret": true,
        "isRequired": true,
        "key": "api_token",
        "type": "config",
        "value": "API_TOKEN"
      }
    ]
  }
}'

PUT /tools/{idOrName}

Updates the current draft of an existing Tool.

Parameters

Request

• Method: PUT
• Path: $BASE_URL/v2/tools/{idOrName}

Request Body

{
  "tool": {
    "name": "string",                     // Name of the Tool. Must be compatible with Open API requested format: operationId_HTTPmethod (e.g., checkWeatherUsingGET_get). Can be updated when using this method.
    "description": "string",              // Description of the tool's purpose. Can be updated when using this method.
    "scope": "string",                    // Tool type; 'api', 'builtin', or 'external'. For Tools created via API this must always be "api".
    "openApi": "string",                  // URL to the OpenAPI specification for the tool. Can be updated when using this method.
    "reportEvents": "string",             // Event reporting level: 'None', 'All', 'Start', 'Finish', or 'Progress'. Can be updated when using this method.
    "parameters": [
      {
        "key": "string",                  // Unique identifier for the parameter. Can be updated when using this method.
        "description": "string",          // Description of the parameter's purpose. Can be updated when using this method.
        "isRequired": boolean,            // Indicates if the parameter is required for tool execution.
        "type": "string",                 // Parameter type: 'config', 'app', or 'context'.
        "value": "string"                 // For context: the context variable name (e.g., 'USER_ID').
      }
      // Additional parameters.
    ]
  }
}

Response

{
  "accessScope": "string",                  // Access scope ("public" or "private").
  "description": "string",                  // Description of the Tool.
  "id": "string",                           // Unique identifier for the Tool.
  "isDraft": boolean,                       // Indicates if the Tool is a draft.
  "messages": [
    {
      "description": "string",              // Message description (e.g., validation warning).
      "type": "string"                      // Message type (e.g., "warning", "info").
    }
    // Additional messages.
  ],
  "name": "string",                         // Name of the Tool.
  "parameters": [
    {
      "key": "string",                      // Unique identifier for the parameter. Can be updated when using this method.
      "description": "string",              // Description of the parameter's purpose. Can be updated when using this method.
      "isRequired": boolean,                // Indicates if the parameter is required for tool execution.
      "type": "string",                     // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                     // For context: the context variable name (e.g., 'USER_ID').
    }
    // Additional parameters.
  ]
"revision": integer,                      // Revision number of the Tool.
  "scope": "string",                        // Tool scope (e.g., "api", "builtin", "custom").
  "status": "string"                        // Tool status (e.g., "active", "draft").
}

cURL Sample

curl -X PUT "$BASE_URL/v2/tools/{idOrName}/upsert?automaticPublish=false" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": {
    "name": "UserContextApiTool",
    "accessScope": "public",
    "publicName": "com.globant.geai.user-context-api",
    "description": "A revised tool that fetches user and project information using context parameters. Now available for public use.",
    "scope": "api",
    "icon": "https://example.com/icons/user-context.png",
    "openApi": "https://example.com/openapi/user-context-api.json",
    "reportEvents": "Start",
    "parameters": [
      {
        "key": "userId",
        "description": "The GUID of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_ID"
      },
      {
        "key": "userEmail",
        "description": "The email of the user making the request.",
        "isRequired": true,
        "type": "context",
        "value": "USER_EMAIL"
      },
      {
        "key": "projectId",
        "description": "The GUID of the project in context.",
        "isRequired": false,
        "type": "context",
        "value": "PROJECT_ID"
      },
      {
        "key": "dateTime",
        "description": "The current date and time at execution.",
        "isRequired": false,
        "type": "context",
        "value": "DATE_TIME"
      },
      {
        "dataType": "String",
        "description": "Configuration that is static, but it is sensitive information. The value is stored in secret-manager",
        "fromSecret": true,
        "isRequired": true,
        "key": "api_token",
        "type": "config",
        "value": "API_TOKEN"
      }
    ]
  }
}'

POST /tools/{idOrName}/publish-revision

Publishes a draft revision of an existing Tool, identified by its ID or name.

After a successful call, the specified draft becomes the latest public version and isDraft is set to false.

Request

• Method: POST
• Path: $BASE_URL/v2/tools/{idOrName}/publish-revision

Request Body

{
  "revision": integer                      // revision number to publish (according to the udpdates conducted).
}

Response

200 OK – Returns the now-published Tool.

{
  "accessScope": "string",                // Tool visibility, e.g., "private" or "public"
  "description": "string",                // Description of the Tool
  "id": "string",                         // Unique identifier of the Tool
  "name": "string",                       // Tool name (unique per project)
  "parameters": [
    {
      "dataType": "string",               // Data type of the parameter (e.g., "String", "Integer")
      "description": "string",            // Description of the parameter
      "isRequired": boolean,              // Whether the parameter is required
      "key": "string",                    // Unique key for the parameter
      "type": "string"                    // Parameter type, e.g., "app", "config", "context"
    }
  // Additional parameters.
  ],
  "revision": integer,                    // Revision number of the Tool. Changes when updates.
  "scope": "string",                      // Tool scope, e.g., "builtin", "api", "external"
  "status": "string",                     // Tool status, e.g., "active", "draft"
  "version": integer                      // Version number of the Tool after it is published.
}

cURL Sample

curl -X POST "$BASE_URL/v2/tools/{idOrName}/publish-revision" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "revision": 2
}'

GET /tools/{idOrName}

Retrieves the complete definition of a Tool identified by its ID or name.

You may request a specific version or allow draft revisions to be returned.

Request

• Method: GET
• Path: $BASE_URL/v2/tools/{idOrName}
• Body: Empty

Parameters

Response

{
  "accessScope": "string",                // Access level for the tool: 'private' or 'public'.
  "description": "string",                // Description of the tool's purpose.
  "id": "string",                         // Unique identifier of the tool (UUID).
  "isDraft": boolean,                     // Indicates if the tool is in draft state.
  "name": "string",                       // Name of the Tool. Must be compatible with Open API requested format: operationId_HTTPmethod (e.g., checkWeatherUsingGET_get).
  "openApi": "string",                    // URL to the OpenAPI specification for the tool.
  "parameters": [
    {
      "description": "string",            // Description of the parameter's purpose.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "key": "string",                    // Unique identifier for the parameter.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'USER_ID').
    },
    {
      "description": "string",            // Description of the parameter's purpose.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "key": "string",                    // Unique identifier for the parameter.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'USER_EMAIL').
    },
    {
      "description": "string",            // Description of the parameter's purpose.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "key": "string",                    // Unique identifier for the parameter.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'PROJECT_ID').
    },
    {
      "description": "string",            // Description of the parameter's purpose.
      "isRequired": boolean,              // Indicates if the parameter is required for tool execution.
      "key": "string",                    // Unique identifier for the parameter.
      "type": "string",                   // Parameter type: 'config', 'app', or 'context'.
      "value": "string"                   // For context: the context variable name (e.g., 'DATE_TIME').
    }
  ],
  "revision": integer,                    // Revision number of the tool.
  "scope": "api",                         // Tool type: 'api', 'builtin', or 'external'. For Tools created via API this must always be "api".
  "status": "string"                      // Status of the tool (e.g., 'active', 'inactive').
}

cURL Sample

curl -X GET "$BASE_URL/v2/tools/{idOrName}" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

GET /tools

Returns a paginated list of Tools in the current Project.

Filters let you target a subset by status or access scope, and you may include draft or external Tools when needed.

Parameters

Request

• Method: GET
• Path: $BASE_URL/v2/tools
• Body: Empty

Response

{
  "information": {
    "Duration":  integer,                // Time taken to process the request in milliseconds.
    "Page":      integer,                // Current page number of the results.
    "PageSize":  integer,                // Number of results per page.
    "Total":     integer                 // Total number of tools found.
  },
  "tools": [
    {
      "accessScope": "string",           // Access scope ("public" or "private").
      "description": "string",           // Description of the Tool.
      "id": "string",                    // Unique identifier for the Tool.
      "isDraft": boolean,                // Indicates if the Tool is a draft.
      "name": "string",                  // Name of the Tool.
      "revision": integer,               // Revision number of the Tool; number increases when an update is conducted.
      "scope": "string",                 // Tool scope (e.g., "builtin", "external", "api").
      "status": "string"                 // Tool status (e.g., "active", "draft").
    }
    // Additional tools.
  ]
}

cURL Sample

curl -X GET "$BASE_URL/v2/tools?status=active&start=0&count=10&accessScope=private&allowDrafts=true&includeExternal=true" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

POST /tools/{idOrName}/config

Sets or updates Config type parameters for the specified Tool at a Project or Organization level.

Request

• Method: POST
• Path: $BASE_URL/v2/tools/{idOrName}/config

Request Body

{
  "parameterDefinition": {                           // Object containing all parameter definitions
    "parameters": [                                  // Array of parameter objects
      {
        "description": "string",                     // Description of the parameter
        "isRequired": boolean,                       // Whether this parameter is required
        "key": "string",                             // Unique key for the parameter
        "type": "string",                            // Type of the parameter (must be "config")
        "value": "string"                            // Value assigned to the parameter
      }
      // Additional parameters.
    ]
  }
}

Response

• 200 OK: The Tool parameters were successfully configurated.

cURL Sample

curl  -X POST "$BASE_URL/v2/tools/{idOrName}/config" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "ProjectId: $GEAI_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "parameterDefinition": {
    "parameters": [
      {
        "dataType": "String",
        "description": "Configuration that is static, but it is sensitive information. The value is stored in secret-manager",
        "fromSecret": true,
        "isRequired": true,
        "key": "api_token",
        "type": "config",
        "value": "API_TOKEN_1"
      }
    ]
  }
}'

GET /tools/{idOrName}/config

Retrieves the Config type parameters from a specified Tool at a Project or Organization level.

Request

• Method: GET
• Path: $BASE_URL/v2/tools/{idOrName}/config
• Body: Empty

Response

{
  "parameters": [
    {
      "dataType":    "string",   // The data type of the parameter value.
      "description": "string",   // Description of the parameter and its usage.
      "fromSecret":  boolean,    // Indicates if the value is sourced from a secret manager.
      "isRequired":  boolean,    // Specifies whether this parameter is required.
      "key":         "string",   // The unique key/name for the parameter.
      "type":        "string",   // The type/category of the parameter (must be "config").
      "value":       "string"    // The value assigned to the parameter (typically a secret or credential).
    }
    // Additional parameters.
  ]
}

cURL Sample

curl -X GET "$BASE_URL/v2/tools/{idOrName}/config \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

DELETE /tools/{idOrName}

Permanently removes a Tool from the current project, using its ID or name.

Request

• Method: DELETE
• Path: $BASE_URL/v2/tools/{idOrName}
• Body: Empty

Response

• 204 No Content: The Tool was successfully deleted.
• 404 Not Found: No Tool exists with the specified idOrName.

cURL Sample

curl -X DELETE "$BASE_URL/v2/tools//{idOrName}" \
  -H "Authorization: Bearer $GEAI_APITOKEN"