Table of contents
Official Content
  • This documentation is valid for:

The Integrations API enables you to manage Integrations used by Globant Enterprise AI.

Integrations group related Tools that belong to the same external service and share configuration settings.

This article covers aspects for Integrations registration, retrieval, update, and deletion as well as security scheme, import and export, among other actions that can be managed through the API.

Check the Generic Variables you need to use the API.

Endpoints List

Method Path Description
GET /tool-plugins Lists all Integrations available in the current project.
GET /tool-plugins/{IdOrName} Retrieves an Integration by id or name.
POST /tool-plugins/import Registers a new Integration by Importing an Integration from a manifest and security scheme (optional automatic publish).
PUT /tool-plugins/{IdOrName} Upserts an Integration (creates or updates).
DELETE /tool-plugins/{IdOrName} Deletes an Integration.
GET /tool-plugins/inspector/security-scheme Discovers the target service’s security scheme (OAuth2, API key, etc.).
POST /tool-plugins/inspector/create-challenge Creates a PKCE challenge and returns an authorizationUrl for user sign-in.
GET /tool-plugins/inspector/manifest Fetches the manifest (Tools + metadata) using the completed challenge
POST /tool-plugins/{idOrName}/publish-tools Publishes all Tools contained in an Integration.
GET /user-interactions/tool-plugins/open Lists open Integrations interactions for the current user in the selected project
PUT /user-interactions/tool-plugins/{IdOrName} Records or updates an open interaction with the specified Integration.
PUT /user-interactions/tool-plugins/{IdOrName}/close Closes the open interaction for the specified Integration.

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
  • Accept: application/json

GET /v3/tool-plugins

Returns all Integrations available in the current project.

Parameters

Name Type Description
detailLevel string Defines the level of detail in the response. Use expanded to include additional related information.
allowDrafts boolean When true, draft versions may be included in the response (if applicable).
start integer Start index for pagination. May be ignored when retrieving a single resource.
count integer Number of results to return. May be ignored when retrieving a single resource.
allowExternal boolean When true, allows inclusion of external Integrations if applicable.

Request

  • Method: GET
  • Path: $BASE_URL/v3/tool-plugins
  • Body: Empty

Response

{
  "information": { // Response metadata for pagination and timing
    "Duration": number, // Processing duration for the request in milliseconds
    "Page": number, // Current page number (1-based)
    "PageSize": number, // Number of items returned per page
    "Total": number // Total number of items available across all pages
  },
  "toolPlugins": [ // List of Integrations records returned in the response
    {
      "accessScope": "string", // Visibility of the Integration ("private" | "public")
      "description": "string", // Human-readable description of the Integration
      "id": "string", // Unique identifier of the Integration (UUID)
      "isReadOnly": boolean,  // True if there are unpublished changes pending
      "name": "string", // Integration name (unique within the project)
      "pendingConfigCredential": boolean, // True if credential configuration is pending
      "pendingPublish": boolean, // True if there are unpublished changes pending
      "status": "string", // Current operational status (e.g., "active", "inactive")
      "type": "string" // Integration category or type (e.g., "Other")
    }
  ]
}

cURL Sample

curl -X GET "$BASE_URL/v3/tool-plugins" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

GET v3/tool-plugins/{IdOrName}

Retrieves an Integration by ID or name.

Request

  • Method: GET
  • Path: $BASE_URL/v3/tool-plugins/{IdOrName}
  • Body: empty

Response

{
  "accessScope": "string", // Visibility of the Integration ("private" | "public")
  "description": "string", // Human-readable description of the Integration
  "id": "string", // Unique identifier of the Integration (UUID)
  "isReadOnly": boolean,  // True if there are unpublished changes pending 
  "manifest": "string", // OpenAPI manifest as a JSON string describing the tool's API
  "name": "string", // Integration name (unique within the project)
  "pendingConfigCredential": boolean, // True if credential configuration is pending
  "pendingPublish": boolean, // True if there are unpublished changes pending
  "securityScheme": { // Security configuration required to call the Integrations' API
    "authLevel": "string", // Authorization level or policy required (e.g., "none", "apiKey", "oauth2")
    "flows": { // OAuth/OpenID flows and related parameters
      "authorizationCode": { // OAuth 2.0 Authorization Code flow configuration
        "scopes": ["string"] // List of OAuth scopes requested during authorization
      },
      "x-additional-parameters": "string" // Vendor-specific extra parameters for security configuration
    },
    "in": "string", // Location of the credential when type is apiKey ("header" | "query" | "cookie")
    "issuer": "string", // Token issuer or authorization server identifier/URL
    "name": "string", // Header or query parameter name that carries the credential (for apiKey)
    "type": "string" // Security scheme type ("apiKey" | "http" | "oauth2" | "openIdConnect")
  },
  "status": "string", // Current operational status (e.g., "active", "inactive")
  "type": "string" // Integration definition type (e.g., "OpenAPI")
}

cURL Sample

curl -X GET "$BASE_URL/v3/tool-plugins/weather-api" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Accept: application/json"

POST /v3/tool-plugins/import

Creates an Integration.

Parameters

Method Path Description
automaticPublish boolean Optional. Default: false. When true, imported Tools are automatically published.

Request

  • Method: POST
  • Path: $BASE_URL/v3/tool-plugins/import

Request Body

{
  "toolPlugin": { // Integration definition to be created
    "name": "string", // Internal name of the Integration
    "description": "string", // Human-readable description of the Integration
    "publicName": "string", // Public identifier for discovery
    "accessScope": "string", // Access scope: "private" | "public"
    "manifest": "string", // OpenAPI 3.0 manifest serialized as a string (JSON or YAML)
    "securityScheme": { // Security configuration for the Integration
      "authLevel": "string", // Authorization level/policy (e.g., "User", "System", "None")
      "flows": { // OAuth/OpenID or custom security flows
        "authorizationCode": { // OAuth 2.0 authorization code flow configuration
          "authorizationUrl": "string", // OAuth authorization endpoint URL
          "tokenUrl": "string", // OAuth token endpoint URL
          "clientId": "string", // Client ID (send as secret/config reference)
          "clientSecret": "string", // Client secret (send as secret/config reference)
          "scopes": ["string"] // List of OAuth scopes requested
        }
      }
    }
  }
}

Response

{
  "accessScope": "string", // Integration access scope: "private" | "public"
  "description": "string", // Human-readable description of the Integration
  "id": "string", // Unique identifier of the Integration (GUID)
  "manifest": "string", // OpenAPI 3.0 manifest serialized as a string (JSON or YAML)
  "name": "string", // Internal name of the Integration
  "parameters": [ // Generated configuration parameters (often mapped to secrets)
    {
      "dataType": "string", // Data type of the parameter (e.g., "String")
      "fromSecret": boolean, // True if the value comes from a secret manager
      "isRequired": boolean, // True if this parameter is required
      "key": "string", // Config path key referencing the parameter
      "type": "string", // Parameter category/type (e.g., "config")
      "value": "string" // Reference/identifier of the stored secret or value
    }
  ],
  "pendingConfigCredential": boolean, // True if credentials/configuration are pending
  "pendingPublish": boolean, // True if a publish operation is pending
  "publicName": "string", // Public identifier used for discovery
  "securityScheme": { // Security configuration resolved for the Integration
    "authLevel": "string", // Authorization level/policy (e.g., "User", "System", "None")
    "flows": { // OAuth/OpenID or custom security flows
      "authorizationCode": { // OAuth 2.0 authorization code flow details
        "authorizationUrl": "string", // OAuth authorization endpoint URL
        "clientId": "string", // Client ID reference/key (not raw secret)
        "clientSecret": "string", // Client secret reference/key (not raw secret)
        "scopes": ["string"], // List of OAuth scopes
        "tokenUrl": "string" // OAuth token endpoint URL
      },
      "x-additional-parameters": { // Vendor-specific additional security parameters
        "key": "string" // Additional parameter value
      }
    },
    "in": "string", // Where credentials are sent: "header" | "query" | "cookie"
    "issuer": "string", // Token issuer/authority URL (for OIDC/JWT)
    "name": "string", // Credential parameter name (e.g., "Authorization")
    "type": "string" // Security scheme type: "oauth2" | "apiKey" | "http" | "mutualTLS" | "openIdConnect"
  },
  "status": "string", // Current publication status: "active" | "inactive" | "draft"
  "tools": [ // Tools generated from the manifest operations
    {
      "accessScope": "string", // Tool access scope: "private" | "public"
      "inputSchema": "string", // Serialized input schema for the Tool (JSON string)
      "name": "string", // Internal Tool operation name
      "openApiJson": "string", // Source reference/indicator for the OpenAPI definition
      "publicName": "string" // Public operation identifier
    }
  ]
}

cURL Sample

curl -X POST "$BASE_URL/v3/tool-plugins/import?automaticPublish=true" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d ' "toolPlugin": {
    "name": "local-geai-agent-tools5",
    "description": "Google Drive OAuth integration",
    "publicName": "local-geai-agent-tools5",
    "accessScope": "public",
    "manifest": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"GDrive Tools\",\"version\":\"1.0.0\"},\"servers\":{\"url\":\"https://www.googleapis.com\"},\"paths\":{\"/drive/v3/files\":{\"get\":{\"operationId\":\"listFiles\",\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
    "securityScheme": {
      "authLevel": "User",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "clientId": "82061177401-pl5surnpjr8evus8fkvpe55p8ovf64k4.apps.googleusercontent.com",
          "clientSecret": "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",
          "scopes": [
            "https://www.googleapis.com/auth/drive",
            "https://www.googleapis.com/auth/gmail.send",
            "https://www.googleapis.com/auth/documents.readonly"
          ]
        }
      }
    }
  }
}'

PUT /v3/tool-plugins/{IdOrName}

Updates an Integration.

Request

  • Method: PUT
  • Path: $BASE_URL/v3/tool-plugins/{IdOrName}

Request Body

{
  "toolPlugin": {
    "name": "string",                     // Internal name
    "publicName": "string",               // Public display name
    "description": "string",              // Description
    "accessScope": "string",              // "public" | "private"
    "manifest": "string",                 // OpenAPI JSON as string
  }
}

Response

{
  "accessScope": "string", // Integration access scope: "private" | "public"
  "description": "string", // Human-readable description of the Integration
  "id": "string", // Unique identifier of the Tool set (GUID)
  "manifest": "string", // OpenAPI 3.0 manifest serialized as JSON or YAML in a string
  "name": "string", // Internal name of the Integration
  "pendingConfigCredential": boolean, // True if credentials/configuration are pending
  "pendingPublish": boolean, // True if a publish operation is pending
  "publicName": "string", // Public identifier used for discovery
  "securityScheme": { // Security configuration associated with the tool set
    "authLevel": "string", // Authorization level or policy (e.g., "none", "user", "system")
    "flows": "string" // OAuth/OpenID or custom security flows
      "authorizationCode": "string" // OAuth 2.0 authorization code flow configuration
        "scopes": ["string"] // List of OAuth scopes required for access
      },
      "x-additional-parameters": "string" // Vendor-specific additional security parameters
        "key": "string" // Additional parameter value
      }
    },
    "in": "string", // Where credentials are sent: "header" | "query" | "cookie"
    "issuer": "string", // Token issuer/authority URL (for OIDC/JWT)
    "name": "string", // Credential parameter name (e.g., "Authorization")
    "type": "string" // Security scheme type: "oauth2" | "apiKey" | "http" | "mutualTLS" | "openIdConnect"
  },
  "status": "string" // Current publication status: "active" | "inactive" | "draft"
}

cURL Sample

curl -X PUT "$BASE_URL/v3/tool-plugins/local-geai-agent-tools" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "toolPlugin": {
    "name": "local-geai-agent-tools",
    "description": "A set of toolActions updated",
    "publicName": "local-geai-agent-tools2",
    "accessScope": "public",
    "manifest": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"...\"}}"
  }
}'

DELETE /v3/tool-plugins/{IdOrName}

Deletes the specified Integration.

Request

  • Method: DELETE
  • Path: $BASE_URL/v3/tool-plugins/{IdOrName}
  • Body: Empty

cURL Sample

curl -X DELETE "$BASE_URL/v3/tool-plugins/{IdOrName}" \
  -H "Authorization: Bearer $GEAI_APITOKEN"

GET /v3/tool-plugins/inspector/security-scheme

Discovers the target service’s security scheme to prefill OAuth2/OpenAPI/MCP authentication settings.

Request

  • Method: GET
  • Path: $BASE_URL/v3/tool-plugins/inspector/security-scheme
  • Body: Empty

Response

{
  "messages": [
    {
      "description": "string",   // Human-readable error message (e.g., "Missing URL parameter")
      "id": integer                    // Application-specific error code (e.g., 4001)
    }
  ],
  "securityScheme": {
    "authLevel": "string",        // Authentication level (if returned; may be empty)
    "flows": {
      "authorizationCode": {
        "scopes": ["string"]    // array of string - OAuth scopes (if applicable; may be empty)
      },
      "x-additional-parameters": {} // object - Additional auth parameters (if applicable)
    },
    "in": "string",               // Where credentials are expected (e.g., "header")
    "issuer": "string",           // Token issuer/authority (if applicable)
    "name": "string",             // Credential parameter name (e.g., "Authorization")
    "type": "string"              // Auth type (e.g., "http", "oauth2", "apiKey")
  }
}

cURL Sample

curl -X PUT "$BASE_URL/v3/tool-plugins/inspector/security-scheme" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Project-Id: $GEAI_PROJECT_ID"

POST /v3/tool-plugins/inspector/create-challenge

Creates a short-lived OAuth2 PKCE challenge. Returns an Authorization URL to complete authentication in a browser.

Request

  • Method: POST
  • Path: $BASE_URL/v3/tool-plugins/inspector/create-challenge

Request Body

{
  "securityScheme": {                               // The (possibly edited) object from Security Scheme Discovery
    "type": "string",                               // "oauth2"
    "authLevel": "string",                          // "User" or other supported levels
    "issuer": "string",                             // OAuth issuer base URL
    "name": "string",                               // Flow name
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "string",               // OAuth authorization endpoint
        "tokenUrl": "string",                       // OAuth token endpoint
        "challengeMethod": "string",                // "S256" (PKCE)
        "clientId": "string"                        // OAuth client_id
      },
      "clientCredentials": {                        // Optional (included if defined)
        "tokenUrl": "string",                       // Token endpoint
        "scope": "string"                           // Scopes (e.g., ".default")
      }
    }
  }
}

Response

{
  "authorizationUrl": "string"                      // URL to open in a browser for user sign-in/consent
  "challengeId": "string",                          // Unique identifier for this PKCE challenge
}

cURL Sample

curl -X POST "$BASE_URL/v3/tool-plugins/inspector/create-challenge" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Project-Id: $GEAI_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d @security-scheme.json

GET /v3/tool-plugins/inspector/manifest

Fetches the manifest (Tools + metadata) from the target service using the completed challenge.

Request

  • Method: GET
  • Path: $BASE_URL/v3/tool-plugins/inspector/manifest
  • Body: Empty

Response

{
  "success": boolean,                               // Indicates if manifest was retrieved successfully
  "manifest": "string"                              // Stringified JSON manifest (see Manifest model)
}

cURL Sample

curl -X GET "$BASE_URL/v3/tool-plugins/inspector/manifest" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Project-Id: $GEAI_PROJECT_ID"

POST /v3/tool-plugins/{idOrName}/publish-tools

Publishes all Tools in the specified Integration. Useful after importing in draft mode.

Request

  • Method: POST
  • Path: $BASE_URL/v3/v3/tool-plugins/{idOrName}/publish-tools
  • Body: Empty

Response

{
   "totalPublished": integer,                          // Total Tools published in this operation
 }

cURL Sample

curl  -X POST "$BASE_URL/v3/tool-plugins/{IdOrName}/publish-tools" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "Project-Id: $GEAI_PROJECT_ID" \
  -H "Content-Type: application/json" \

GET /user-interactions/tool-plugins/open

Lists open Integration interactions for the current user in the selected Project.

Request

  • Method: GET
  • Path: $BASE_URL/v2/user-interactions/tool-plugins/open
  • Body: Empty

Response

{
  "interactions": [
    {
      "entity": "string",                    // Always "tool-plugin"
      "id": "string",                        // Integration unique identifier (GUID)
      "isOpen": boolean,                        // Indicates if the interaction is open
      "lastInteractionDateTime": "string",    // Last interaction timestamp (ISO 8601, e.g., "2025-11-03T18:59:03")
      "name": "string",                      // Integration name
      "organizationId": "string",            // Organization GUID
      "projectId": "string"                  // Project GUID
    }
  ]
}

cURL Sample

curl -X GET "$BASE_URL/v2/user-interactions/tool-plugins/open" \
  -H "Authorization: Bearer $GEAI_APITOKEN" \
  -H "ProjectId: $GEAI_PROJECT_ID" \
  -H "Accept: application/json"

PUT /v2/user-interactions/tool-plugins/{IdOrName}

Records an open interaction for the specified Integration.

Request

  • Method: PUT
  • Path: $BASE_URL/v2/user-interactions/tool-plugins/{IdOrName}
  • Body: Empty

Response

{
  "entity": "string",     // "ToolPlugin"
  "id": "string",         // Integration unique identifier (GUID)
  "isOpen": boolean         // True if interaction is open
}

cURL Sample

curl -X PUT "$BASE_URL/v2/user-interactions/tool-plugins/{IdOrName}" \
  -H "Authorization: Bearer $OAuth_accesstoken" \
  -H "ProjectId: $GEAI_PROJECT_ID" \
  -H "Accept: application/json"

PUT /v2/user-interactions/tool-plugins/{IdOrName}/close

Closes the open interaction for the specified Integration.

Request

  • Method: PUT
  • Path: $BASE_URL/v2/user-interactions/tool-plugins/{IdOrName}/close}
  • Body: Empty

Response

{
  "entity": "string",     // "tool-plugin"
  "id": "string",         // Integration unique identifier (GUID)
  "isOpen": false         // Interaction is now closed
}

cURL Sample

curl -X PUT "$BASE_URL/v2/user-interactions/tool-plugins/{IdOrName}/close" \
  -H "Authorization: Bearer $OAuth_accesstoken" \
  -H "ProjectId: $GEAI_PROJECT_ID" \
  -H "Accept: application/json"
—
Last update: 2 March 2026 by slinares
Last update: December 2025 | © GeneXus. All rights reserved. GeneXus Powered by Globant