.png)
IBM watsonx Integration Guide
IBM watsonx integrates with enterprise systems primarily through IBM Cloud REST APIs secured by IAM, with Martini orchestrating inference, data, governance, and synchronization workflows.
IBM watsonx integration options at a glance
IBM watsonx provides REST APIs across its watsonx.ai, watsonx.data, and watsonx.governance components, with IBM Cloud IAM used to exchange API keys for short-lived bearer tokens. Martini can consume these APIs to submit inference requests, retrieve model and deployment information, synchronize projects and assets, and exchange applicable governance or data resources. Asynchronous and batch behavior is service- and operation-specific, so workflows can persist job identifiers and poll documented status endpoints. File and asset handling is also component-specific, while watsonx.data access depends on configured engines and sources. General watsonx webhooks are not confirmed, making scheduled polling a practical synchronization pattern.
| Integration point | Supported by IBM watsonx? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Submit prompts and inference requests, retrieve foundation model and deployment information, and manage supported projects, assets, prompt templates, and governance resources. | Martini can consume IBM watsonx and IBM Cloud REST APIs, map request and response payloads, apply business rules, and expose reusable APIs for internal consumers. |
| Authentication | Yes | IBM Cloud API keys are exchanged for short-lived IAM bearer tokens, with access controlled by account, service, resource, project, and deployment permissions. | Martini can orchestrate token acquisition, store API keys in secure environment configuration, refresh tokens as required, and pass bearer tokens to subsequent calls. |
| Bulk / async / batch APIs | Limited | Some inference, evaluation, data preparation, and deployment operations support asynchronous or batch behavior, depending on the component and operation. | Martini can persist operation or job identifiers, poll documented status endpoints, enforce timeouts, and retrieve results with bounded retries. |
| File / attachment APIs | Limited | Applicable watsonx services support project assets and data files, while IBM Cloud Object Storage may be used for larger documents and analytical data. | Martini can exchange files or object references through documented APIs, track processing state, transform metadata, and pass content or locations to the relevant service. |
| Database / analytics access | Limited | watsonx.data supports data-source and analytical integrations, but available database access depends on configured engines, connectors, and deployment architecture. | Martini can use documented watsonx.data interfaces or explicitly available database protocols and can synchronize selected data or metadata through workflows. |
| Scheduled synchronization | Yes | Polling is appropriate for project, asset, deployment, model, and governance changes where a general watsonx webhook mechanism is unavailable. | Martini scheduler-triggered workflows can use timestamps, page tokens, stable identifiers, and checkpoints for incremental synchronization. |
| Webhooks / outbound callbacks | Not confirmed | A universal watsonx webhook or callback framework for model, project, asset, deployment, and governance events was not confirmed. | Martini can consume webhooks from other systems and can use scheduled polling or documented IBM event services where applicable instead of assuming universal watsonx callbacks. |
| GraphQL APIs | Not confirmed | No general IBM watsonx GraphQL API was confirmed for watsonx.ai, watsonx.data, or watsonx.governance. | Martini should consume the documented REST APIs; GraphQL can be used only if a separately documented IBM endpoint is identified. |
| SOAP APIs | Not confirmed | No current SOAP interface was confirmed for the core IBM watsonx services. | Martini should use IBM watsonx REST APIs and IAM rather than assuming a SOAP integration surface. |
How IBM watsonx exposes data and business events
IBM watsonx REST APIs
REST is the primary confirmed integration surface for IBM watsonx. Depending on the component, APIs can submit inference requests, retrieve foundation model and deployment information, manage projects and assets, and interact with watsonx.data or governance resources.
Martini implementation pattern
Martini exposes or invokes an API-led workflow that obtains an IBM IAM bearer token, builds a component-specific request, validates identifiers such as project_id or deployment IDs, transforms the response, and routes the result to an enterprise application or data store.
Implementation sequence
IBM watsonx asynchronous operations
Some watsonx inference, evaluation, data preparation, and deployment operations are asynchronous or batch-oriented. Support and status behavior varies by component and endpoint.
Martini implementation pattern
Martini submits the operation, stores the returned job or operation identifier, and uses a controlled polling workflow to retrieve status and results. The workflow applies timeout, retry, and failure-routing rules rather than treating an accepted request as completed.
Implementation sequence
IBM watsonx scheduled synchronization
A general webhook framework for watsonx changes was not confirmed. Scheduled polling is therefore a practical method for synchronizing projects, assets, deployments, models, or governance resources.
Martini implementation pattern
A Martini scheduler-triggered workflow retrieves paginated resources, compares timestamps and stable identifiers with a checkpoint, maps changed objects to the target model, and records progress so subsequent runs are incremental.
Implementation sequence
IBM Cloud Object Storage and watsonx files
Applicable watsonx services can work with project assets and data files, while IBM Cloud Object Storage is commonly used for larger documents and analytical data. There is no single universal watsonx attachment model.
Martini implementation pattern
Martini receives or retrieves a document, stores it or obtains its object location through documented interfaces, tracks the correlation identifier, and passes content or a reference to the applicable watsonx operation. Cleanup and retention rules are applied separately.
Implementation sequence
IBM watsonx.data access
watsonx.data connects analytical workloads with configured data sources and engines. Database and catalog access is deployment-specific and should be confirmed for the customer environment.
Martini implementation pattern
Martini uses the documented watsonx.data API or explicitly exposed database protocol to retrieve or update approved metadata and data. It applies source-specific mappings, permissions, pagination, and checkpoint handling.
Implementation sequence
Common IBM watsonx integration patterns
Pattern 1: Submit enterprise requests to watsonx.ai
When to use this pattern
Use this pattern when Salesforce, ServiceNow, SAP S/4HANA, Jira, or another application needs classification, summarization, extraction, assisted responses, or other model inference. It centralizes validation, security, model configuration, and response normalization.
Integration direction
Example Mapping
| IBM watsonx Field | Canonical Field | Target Field |
|---|---|---|
| sourceId | correlationId | request metadata |
| sourceText | inputContent | prompt or input |
| requestedOperation | inferenceTask | model request configuration |
| generatedText | resultContent | application response |
Martini implementation pattern
A Martini API or workflow receives the request, validates required content and policy constraints, obtains an IAM token, invokes the selected model or deployment, and normalizes the response. Business rules can reject unsupported models or sensitive payloads, while error handling preserves the correlation ID for retry or review.
Martini capabilities used
- APIs
- workflows
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Process documents with Object Storage and watsonx.ai
When to use this pattern
Use this pattern for documents or datasets that should be tracked independently from inference requests or are too large for direct payload exchange. It supports controlled intake, processing status, result storage, and later audit.
Integration direction
Example Mapping
| IBM watsonx Field | Canonical Field | Target Field |
|---|---|---|
| documentId | sourceDocumentId | object key or asset identifier |
| contentType | mediaType | request content metadata |
| objectLocation | sourceReference | watsonx asset or input reference |
| modelOutput | processedResult | stored result object |
Martini implementation pattern
Martini receives the document or its location, validates size and sensitivity, stores or retrieves the object, and submits the supported content or reference to watsonx.ai. It tracks state through correlation IDs, stores normalized results, applies retention rules, and routes transient failures to bounded retry.
Martini capabilities used
- workflows
- API consumption
- file handling
- data mapping
- business rules
- error handling
Pattern 3: Synchronize watsonx projects and deployments
When to use this pattern
Use this pattern when an enterprise catalog, reporting database, or service platform needs current watsonx project, asset, deployment, or model metadata. It is appropriate where no general webhook mechanism is available.
Integration direction
Example Mapping
| IBM watsonx Field | Canonical Field | Target Field |
|---|---|---|
| id | externalResourceId | source identifier |
| name | resourceName | catalog name |
| modified_at | lastChangedAt | last modified timestamp |
| status | lifecycleStatus | catalog or service status |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated resources, filters by checkpoint or modification timestamp, maps component-specific fields to a canonical model, and upserts the target record. Stable identifiers and source-to-target mappings prevent duplicates; throttling, retries, and partial-run checkpoints support recovery.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination handling
- data mapping
- business rules
- error handling
Pattern 4: Synchronize AI governance metadata
When to use this pattern
Use this pattern when watsonx.governance resources such as use cases or factsheets must be exchanged with ServiceNow, Jira, or an internal risk platform. Exact resource names and operations should be confirmed for the deployed governance version.
Integration direction
Example Mapping
| IBM watsonx Field | Canonical Field | Target Field |
|---|---|---|
| useCaseId | governanceItemId | record identifier |
| factSheetStatus | reviewStatus | approval or task status |
| riskInformation | riskSummary | risk fields |
| approvalDate | approvedAt | approval timestamp |
Martini implementation pattern
Martini retrieves or receives applicable governance metadata, validates the deployment-specific resource shape, maps it to the target governance model, and applies approval and routing rules before updating ServiceNow or another platform. Unknown schema fields, authorization failures, and duplicate updates are isolated for review.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- validation
- error handling
Applications commonly integrated with IBM watsonx
IBM watsonx can participate in API-led enterprise architectures alongside storage, databases, business applications, and governance platforms. The exact integration boundary depends on the watsonx component, deployment, permissions, and available APIs.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| IBM Cloud Object Storage | Store documents, model inputs, generated outputs, and analytical files that are too large or unsuitable for direct API payloads. | IBM Cloud Object Storage → Martini → IBM watsonx | Martini retrieves or stores the object, tracks its location and correlation identifier, transforms metadata, and submits the applicable object reference or content to watsonx.ai or watsonx.data. Failures are routed for bounded retry or review. |
| IBM Db2 | Make relational enterprise data or metadata available to watsonx.data and AI workflows. | IBM Db2 → Martini → IBM watsonx | Martini reads approved Db2 data through documented database connectivity or APIs, applies filtering and protection rules, maps records to watsonx data or inference requests, and persists processing checkpoints. |
| PostgreSQL | Provide operational or analytical source data for watsonx.data workloads and synchronize selected metadata. | PostgreSQL → Martini → IBM watsonx | A scheduled Martini workflow reads changed PostgreSQL rows, normalizes them into the target watsonx model, and records stable identifiers and timestamps to support incremental processing and duplicate prevention. |
| Snowflake | Use governed warehouse data in AI and analytical workflows or exchange data-platform metadata. | Snowflake → Martini → IBM watsonx | Martini orchestrates approved extracts or metadata calls, applies schema and access rules, and sends the resulting data or references to watsonx.data. Deployment-specific source support must be confirmed before implementation. |
| Salesforce | Apply classification, summarization, extraction, or assisted response generation to customer, account, or case information. | Salesforce → Martini → IBM watsonx | Martini receives Salesforce data, validates and minimizes the payload, invokes a watsonx.ai model through IAM-authenticated REST calls, and writes the normalized result back when business rules permit. |
| ServiceNow | Summarize incidents, classify requests, and coordinate AI review or governance tasks. | ServiceNow → Martini → IBM watsonx | A Martini workflow retrieves or receives ServiceNow data, invokes watsonx.ai, applies confidence and routing rules, and updates the ServiceNow item or sends it to an approval queue. Errors retain the source identifier for replay. |
| SAP S/4HANA | Process business documents and operational data through AI-assisted classification, extraction, or analysis. | SAP S/4HANA → Martini → IBM watsonx | Martini maps selected SAP payloads into watsonx.ai requests, applies data minimization and validation, and returns approved classifications or extracted values to SAP with correlation and retry handling. |
| Jira | Enrich software and operational tickets with summaries, classification, routing, or governance review information. | Jira → Martini → IBM watsonx | Martini polls or receives Jira changes where supported, prepares the issue content for watsonx.ai, transforms the response into Jira fields or comments, and prevents duplicate updates with stable issue identifiers. |
How to build a IBM watsonx integration in Martini
Objective
Configure the IBM regional endpoint, API key, service ID where applicable, project or deployment identifiers, and target-system credentials without embedding secrets in workflow logic.
Instructions in Martini
- Store IBM API keys and target credentials in secure environment configuration.
- Keep region, project_id, deployment, and space identifiers configurable by environment.
- Define the permitted IAM roles and service access for each integration.
Objective
Select an API request, schedule, file process, or application event based on the watsonx operation and the availability of outbound notifications.
Instructions in Martini
- Use a Martini API for synchronous application requests.
- Use a scheduler for polling projects, assets, deployments, or governance resources.
- Do not assume a universal watsonx webhook; confirm any IBM event mechanism separately.
Objective
Acquire source data, token credentials, watsonx resources, files, or operation results using the documented interface for the selected component.
Instructions in Martini
- Exchange the IBM API key for a short-lived IAM bearer token.
- Handle pagination, continuation links, and service-specific response formats.
- Persist job identifiers when an operation is asynchronous.
Objective
Coordinate authentication, API calls, file or database access, conditional routing, polling, and target-system operations in a maintainable Martini workflow.
Instructions in Martini
- Separate token acquisition from business processing where reuse is beneficial.
- Branch on synchronous, asynchronous, success, retryable, and terminal failure states.
- Use correlation IDs across all upstream and downstream calls.
Objective
Convert application, file, data-source, and watsonx payloads into a canonical model while accounting for component-specific fields and model response formats.
Instructions in Martini
- Map project, deployment, asset, model, and governance identifiers explicitly.
- Validate prompt, model, parameter, and payload compatibility before invocation.
- Normalize inference output and retain required source metadata.
Objective
Enforce data minimization, authorization, model selection, confidence, approval, and routing policies before committing results.
Instructions in Martini
- Reject or route sensitive content according to the environment policy.
- Check project, deployment, model, and target-system permissions.
- Apply idempotency rules before creating assets or governance records.
Common IBM watsonx data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Projects | Organize watsonx.ai assets, data, notebooks, prompt templates, and model-related work; many operations require a project_id. | Enterprise catalogs, reporting databases, ServiceNow, and internal application platforms | Martini retrieves and synchronizes project metadata, validates project scope, stores stable identifiers, and applies environment-specific configuration. |
| Foundation models | Provide model identifiers for generation, embeddings, classification, summarization, and other inference operations. | Enterprise applications, document-processing workflows, reporting systems, and governance platforms | Martini validates model configuration and supported parameters, submits requests through REST APIs, normalizes responses, and records correlation details. |
| Prompt templates | Store reusable prompts and parameters for repeatable generation or inference workflows. | Application services, content workflows, governance platforms, and knowledge processes | Martini maps business inputs to template parameters, applies validation and policy rules, invokes the applicable operation, and preserves version or identifier data. |
| Deployments | Expose models or assets for inference and operational use, depending on the watsonx.ai architecture. | Enterprise APIs, application platforms, monitoring systems, and governance tools | Martini retrieves deployment status, invokes documented deployment endpoints, polls long-running operations, and routes unavailable or failed deployments for review. |
| Assets | Represent project or space content such as data files, notebooks, models, and prompt templates. | IBM Cloud Object Storage, data catalogs, reporting databases, and enterprise governance tools | Martini handles service-specific asset APIs, maps asset metadata, exchanges large content through approved storage paths, and prevents duplicate creation. |
| Data sources and catalogs | Represent connected sources, catalogs, schemas, and tables used by watsonx.data analytical workloads. | IBM Db2, PostgreSQL, Snowflake, object storage, and enterprise data catalogs | Martini synchronizes supported metadata through APIs or explicitly available database protocols while respecting deployment-specific access and schema rules. |
Authentication and security considerations
IBM Cloud IAM authentication
IBM watsonx integrations generally use an IBM Cloud API key exchanged for a short-lived IAM bearer token. Requests then use the token in the Authorization header, with access constrained by account roles, service roles, resource groups, projects, deployments, and service-specific permissions.
Secure configuration
- Store API keys, service identifiers, regional endpoints, project IDs, and deployment IDs in protected environment configuration.
- Keep credentials separate from workflow logic and use least-privilege IAM access.
- Do not log API keys, bearer tokens, full confidential prompts, or sensitive model responses.
- Apply data minimization and environment-specific controls to prompts, documents, generated outputs, and governance metadata.
Operational considerations for IBM watsonx integrations
Reliability and throughput
- Respect IBM Cloud, service, model, and deployment quotas with throttling and bounded exponential backoff.
- Handle pagination and continuation tokens for project, asset, deployment, model, and governance list operations.
- For asynchronous operations, persist job identifiers, poll documented status endpoints, and enforce timeout and terminal-failure handling.
- Use stable identifiers, correlation IDs, and checkpoints to make retries idempotent and prevent duplicate assets or governance records.
Payloads and change management
- Use Object Storage for appropriate large files and account for payload limits, encoding, lifecycle, and cleanup.
- Validate model identifiers, parameters, context limits, project scope, and deployment availability before invocation.
- Isolate mappings from business logic and monitor IBM API, model catalog, and response-schema changes.
- Test token acquisition, permissions, regional endpoints, rate limits, pagination, redaction, retries, and unavailable deployments before production.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini provides a maintainable workflow boundary between enterprise applications and IBM watsonx. It can authenticate, invoke REST APIs, poll asynchronous operations, exchange files, apply business rules, and route results without duplicating integration logic across scripts.
Reusable integration behavior
Teams can expose controlled Martini APIs for inference or governance use cases, reuse token and transformation logic, and apply consistent validation, idempotency, error handling, and observability patterns across watsonx.ai, watsonx.data, and applicable governance integrations.
Adaptable architecture
Because watsonx capabilities vary by component and deployment, Martini workflows can isolate provider-specific mappings while connecting to databases, files, storage, and enterprise applications through their documented interfaces. This reduces point-to-point coupling and makes schema or endpoint changes easier to manage.
Frequently asked questions
IBM watsonx is primarily integrated through IBM Cloud REST APIs secured by IAM. Depending on the component, integrations can submit watsonx.ai inference requests, manage projects and assets, retrieve deployment information, interact with watsonx.data, and exchange governance resources. Scheduled polling is appropriate where general watsonx webhooks are not available.
Yes. Martini can consume the documented IBM watsonx REST APIs, obtain IAM bearer tokens from IBM Cloud API keys, orchestrate synchronous or asynchronous operations, transform payloads, and synchronize applicable files, data, projects, assets, deployments, and governance metadata.
No. A dedicated IBM watsonx connector is not required. Martini can integrate using IBM watsonx REST APIs, IBM Cloud IAM authentication, IBM Cloud Object Storage APIs where applicable, and explicitly documented watsonx.data or other supported endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate IBM watsonx. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from IBM, cloud infrastructure, storage, or other third-party systems based on usage and deployment model.
REST APIs and IBM Cloud IAM are the primary recommended mechanisms. Use component-specific asynchronous or batch operations where documented, Object Storage for appropriate large files, and watsonx.data APIs or database protocols only when available in the configured deployment. GraphQL, SOAP, and a universal webhook framework were not confirmed.
A general watsonx webhook or outbound callback framework covering projects, assets, models, deployments, and governance events was not confirmed. Martini can use scheduled workflows to poll documented APIs, compare timestamps or statuses, and process changes incrementally.
Martini can run scheduled or API-triggered workflows that retrieve paginated resources, compare stable identifiers and modification timestamps with stored checkpoints, map component-specific objects to a canonical model, and upsert target records. Asynchronous operations can be tracked through persisted job identifiers and status polling.
Martini can distinguish authentication, authorization, throttling, invalid identifiers, unavailable deployments, validation, timeout, and upstream service errors. Workflows can use bounded retries and backoff, correlation IDs, stable source-to-target mappings, idempotency checks, checkpoints, and failure routing to avoid duplicate processing and support recovery.
Related Martini documentation
Workflows
Data
Build reliable IBM watsonx integrations with Martini
Use Martini to connect enterprise applications and data sources to IBM watsonx through secure API-led workflows, reusable transformations, asynchronous processing, and operational controls.