How to Integrate Retool with IBM Watson

IBM Cloud uses IAM (Identity and Access Management) for authentication across all Watson services. You will generate an IBM Cloud API key that Retool uses to obtain short-lived access tokens. Log in to IBM Cloud at https://cloud.ibm.com and click 'Manage' in the top navigation, then select 'Access (IAM)'. In the IAM dashboard left sidebar, click 'API keys' under 'IBM Cloud API keys'. Click 'Create an IBM Cloud API key'. Give it a descriptive name such as 'Retool-Watson-Integration' and an optional description. Click Create — IBM Cloud displays the API key value once. Copy it immediately and store it securely; you cannot retrieve it again after closing this dialog. Next, locate your Watson service credentials. In IBM Cloud, click 'Resource List' in the navigation. Find your Watson service instance (e.g., 'Natural Language Understanding-xyz'). Click on it to open the service details. Click 'Credentials' in the left sidebar, then 'New credential' if no credentials exist. Expand the credential to view the API key (specific to this service instance) and the URL. Note the service URL — it has the format https://{region}.ml.cloud.ibm.com for NLU, https://api.{region}.assistant.watson.cloud.ibm.com for Assistant, and https://api.{region}.discovery.watson.cloud.ibm.com for Discovery. Copy the service URL for each Watson service you plan to use.

IBM Cloud IAM requires exchanging your API key for a short-lived Bearer token before making Watson API calls. This token expires after 60 minutes and must be refreshed. Retool's Custom Auth feature handles this pattern cleanly. In Retool, click the Resources tab and then Add Resource. Select REST API. Name the resource for your specific Watson service, for example 'Watson NLU'. In the Base URL field, enter the service URL for that Watson instance (e.g., https://us-south.ml.cloud.ibm.com). Scroll to Authentication and select 'Custom Auth' from the dropdown. In the Custom Auth Login steps, add a 'Make request' step: set the URL to https://iam.cloud.ibm.com/identity/token, Method to POST, set Content-Type header to application/x-www-form-urlencoded, and the body to: grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={{ YOUR_IBM_API_KEY }} (replace with your actual key or a Configuration Variable reference). Add a second step 'Parse response' and extract access_token from the JSON response body. Add a third step 'Set headers' and set Authorization to Bearer {{ access_token }}. In the 'When to refresh auth' section, set the refresh trigger to 'On 401 response' and also set a proactive refresh interval of 50 minutes (since tokens expire after 60 minutes). Save the resource. This setup means Retool automatically obtains and refreshes IBM IAM tokens transparently before making Watson API calls.

1// Custom Auth Step 1: Exchange IBM API key for IAM access token
2// Method: POST
3// URL: https://iam.cloud.ibm.com/identity/token
4// Content-Type: application/x-www-form-urlencoded
5// Body:
6grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={{ retoolContext.configVars.IBM_API_KEY }}

Create your first Watson NLU query to verify the connection and build the core analysis capability. In a Retool app, open the Code panel and click + to add a new query. Select your Watson NLU resource. Name the query 'analyzeText'. Set the Method to POST. For the Path, enter /v1/analyze with a URL parameter 'version' set to 2023-04-15 (or check the Watson NLU documentation for the current version date). Set the Body Type to JSON. In the Body field, construct the analysis request: the 'text' field contains the text to analyze (bind this to a Multiline Text Input component or a database record's text field), and the 'features' object specifies what to extract. A standard configuration requests sentiment (document-level and targeted), entities (with limit 10 and sentiment analysis enabled), keywords (with limit 10 and sentiment enabled), and categories. Run the query with a sample text to verify the response. The response includes document-level sentiment (label: 'positive'/'negative'/'neutral', score: -1 to 1), a list of extracted entities with type, text, sentiment, and relevance, and a list of keywords with relevance scores. Add a JavaScript transformer to extract the most useful fields from the nested response structure for display in Retool Tables.

1{
2  "text": {{ JSON.stringify(textInput.value || 'Sample text to analyze') }},
3  "features": {
4    "sentiment": {
5      "document": true
6    },
7    "entities": {
8      "limit": 10,
9      "sentiment": true
10    },
11    "keywords": {
12      "limit": 10,
13      "sentiment": true
14    },
15    "categories": {
16      "limit": 5
17    }
18  },
19  "language": "en"
20}

Assemble the dashboard components around the Watson NLU query. From the component panel, drag a Multiline Text Input onto the canvas for direct text analysis — name it 'textInput'. Drag a Button below it labeled 'Analyze Text' that triggers the analyzeText query on click. Add Statistic components to show the document-level sentiment: one for sentiment label ({{ analyzeText.data.sentiment?.document?.label || 'N/A' }}) and one for sentiment score formatted as a percentage. Drag a Table component and set its data to display the extracted entities: bind to a transformer that formats analyzeText.data.entities into rows with columns for text, type, and sentiment label. Add a second Table for keywords with relevance score. To build a batch analysis workflow — processing multiple texts from a database — create a second query named 'getTicketsForAnalysis'. Configure it to query your PostgreSQL database for support tickets. Then create a JavaScript query named 'batchAnalyze' that iterates through the tickets and calls Watson NLU for each one using .trigger() with text parameters. Collect results into an array and display them in a results Table. Note that batch processing many texts synchronously can be slow — for large batches, use Retool Workflows with a Loop block to process tickets asynchronously and store results back in your database. Add a Chart component showing sentiment distribution across the batch results using a Bar chart configured with 'positive', 'neutral', 'negative' as the x-axis categories and count as the y-axis.

1// Transformer: format Watson NLU entities for Table display
2const entities = data.entities || [];
3return entities
4  .sort((a, b) => b.relevance - a.relevance)
5  .map(entity => ({
6    text: entity.text,
7    type: entity.type,
8    relevance: (entity.relevance * 100).toFixed(0) + '%',
9    sentiment: entity.sentiment?.label || 'neutral',
10    sentiment_score: entity.sentiment?.score?.toFixed(3) || '0.000',
11    count: entity.count || 1
12  }));

For teams using Watson Discovery or Watson Assistant, create additional REST API Resources following the same IAM auth pattern. Watson Discovery queries are sent as POST requests to /v2/projects/{project_id}/query with a JSON body specifying the natural language query, count (number of results), and passages configuration (to extract relevant text excerpts). The project_id is found in your Watson Discovery service dashboard. Create a query in Retool with Method POST, the Discovery service URL as the resource base, and configure the query body to bind the natural language query text to a Text Input component. Watson Assistant monitoring queries use GET requests to /v2/assistants/{assistant_id}/logs to retrieve conversation logs. The assistant_id is found in your Watson Assistant service settings under 'API details'. Create a query in Retool that retrieves logs with pagination, and add a transformer that extracts session ID, primary intent, confidence score, and conversation outcome from the nested log structure. Add a Chart tracking daily session counts and intent recognition rates. For complex integrations involving multiple Watson services, custom IAM token management, and Retool Workflows that automate batch NLP processing across large document collections, RapidDev's team can help architect and build your Retool AI operations platform.

1// Watson Discovery query request body
2{
3  "query": {{ JSON.stringify(searchInput.value) }},
4  "count": 10,
5  "passages": {
6    "enabled": true,
7    "count": 3,
8    "fields": ["text", "body"],
9    "characters": 400
10  },
11  "highlight": true
12}