Introduction
Enterprises rely on IBM webMethods Integration to connect cloud and on-premises applications, APIs, and services at scale. While the UI is convenient for manual configuration, organizations increasingly adopt an API-first approach to gain speed, automation, and integration with DevOps pipelines.
The webMethods Integration APIs expose a wide range of endpoints for managing projects, workflows, executions, and tenant administration. This guide introduces the fundamentals of working with these APIs so that developers, platform teams, and tenant admins can start automating common integration tasks.
Why Use Integration APIs?
- Automation: Integrate with CI/CD pipelines for zero-touch deployments.
- Scalability: Deploy across multiple tenants without manual intervention
- Consistency: Reduce human error by automating repeatable tasks.
- Integration: Seamlessly connect with DevOps toolchains (GitHub Actions, Jenkins, Azure DevOps, etc.).
- Flexibility: Update parameters dynamically for different environments (Dev, Test, Prod).
Target Audience
This guide is intended for technical teams who manage, develop, and operate integrations in IBM webMethods.io. It is particularly relevant for:
- Platform Teams: who design and maintain CI/CD pipelines.
- Developers: who build and maintain integrations.
- Tenant Teams: who handle user, project, and environment administration.
Pre-requisites
- Admin access to an IBM webMethods.io Integration tenant.
- Basic understanding of REST APIs and JSON.
- Tooling such as Postman, cURL, etc.
Authentication Options
All API requests to IBM webMethods.io Integration require authentication. You can authenticate using either of the following methods:
- Username and Password: Provide your tenant credentials to obtain a session token.
- API Key: Use a pre-generated API key from the tenant settings for direct access.
Ensure that the credentials or API key have sufficient permissions for the operations you intend to perform.
Use-case
In enterprise environments, integrations often span multiple stages — from Development to Testing, and ultimately to Production. While the webMethods.io UI provides a user-friendly interface for managing these transitions, manual deployment can be time-consuming and susceptible to human error, especially when repeated across environments or tenants.
To improve consistency and efficiency, organizations are increasingly adopting an API-first approach. Automating deployments using webMethods Integration APIs ensures repeatability, reduces manual effort, and integrates seamlessly with CI/CD pipelines — making it ideal for scaling integration operations across teams and environments.
As an example, let’s look at how a project can be deployed from one tenant to another using APIs. The process involves:
- Export Project from Source Tenant
- Import Project into Target Tenant
- Update Parameters for Target Environment
- Retrieve Project Metadata (Validation)
- Run Sanity Workflows
- Retrieve Execution Summary
Step-by-Step with API Requests
1. Export Project (Source Tenant)
API Reference
Request
URL Syntax: <SourceTenantName>/apis/v1/rest/projects/<project>/export
Method: POST
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
"projectName": "OrderProcessing",
"includeExecutions": false
}
Response
A .zip file containing the exported project is returned.
2. Import Project (Target Tenant)
API Reference
Request
URL syntax: <TargetTenantName>/apis/v1/rest/project-import
Method: POST
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: multipart/form-data
file=@exported_project.zip
overwrite=true
Response
{
"output": {
"status": "<import_status>"
}
}
3. Update Project Parameters (Target-Specific)
API Reference
Request
URL syntax: <TargetTenantName>/apis/v1/rest/projects/:project/params/param_uid
Method: PUT
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
"key": "key4",
"value": "value4",
"required": true,
"isPassword": true
}
Response
{
"output": {
"uid": "fl178c9bfd1911cd6d70209b",
"param": {
"key": "key4",
"required": true,
"isPassword": true,
"hasError": false
},
"project_uid": "fl79906e0ed9359a6cf82bb7",
"tenant_uid": "flf12fd616f04779d059d3b8"
}
}
4. Retrieve Project Metadata (Validation)
API Reference
Request
URL Syntax: <TargetTenantName>/apis/v1/rest/projects/:project
Method: GET
Authorization: Bearer <ACCESS_TOKEN>
Response
{
"output": {
"name": "ProjectName",
"uid": "fl79906e0ed9359a6cf82bb7",
"tenant_uid": "flf12fd616f04779d059d3b8",
"workflow_count": 3,
"flowservice_count": 2
}
}
5. Run Sanity Workflow
API Reference
Request
URL Syntax - <TargetTenantName>/apis/v1/rest/projects/:project/workflows/:workflow/run
Method: POST
Authorization: Bearer <ACCESS_TOKEN>
Response
{
"run_id": "122344",
"response": "OK",
"status": "Status",
"workflow_uid": " fl79906e0ed9359a6cf82bb7",
"tenant_uid": " flf12fd616f04779d059d3b8",
"project_uid": " fl79906e0ed9359a6cf82bb7",
"env_uid": "f86gsuunsb8uu8585877s7s767"
}
6. Retrieve Execution Summary
API Reference
Request
URL Syntax: <TargetTenantName>/apis/v1/rest/monitor/summary
Method: POST
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
{
"start_date": "2025-08-15T08:00:00.000Z",
"end_date": "2025-08-20T08:00:00.000Z",
"workflows":[“ fl9579f2ec6f01678d0d1660”],
"execution_status": [“success”, “failed”]
}
}Response
{
"output": {
"summary": {
"success": 4461
},
"graph": {
"count": 1,
"logs": [
{
"uid": "vbid76b7b32e4028d74fb66f298d275e9e1774fcedab1430",
"count_transaction": false,
"execution_status": "success",
"flow_name": "SimpleEchoWorkflow",
"flow_uid": "fl344f0c0cb0cee485d84160e",
"project_uid": "fl37e6d39e20159b799s962e6",
"restarted": false,
"requested_at": "02/10/2025 07:48 AM UTC",
"project_name": "project",
"execution_source": "webhook",
"restart_history": [],
"restarted_from": "-"
}
]
}
}
}
Here’s a suggested section you can add to your document titled “Error Handling and Troubleshooting”:
Error Handling and Troubleshooting
When working with IBM webMethods Integration APIs, it's important to anticipate and handle common errors gracefully. Below are typical HTTP status codes and their meanings, along with recommended actions:
401 Unauthorized
Cause: Invalid or missing authentication credentials (API key or token).
Resolution:
- Ensure the Authorization header is correctly formatted:
Authorization: Bearer <ACCESS_TOKEN>
- Verify that the token is active and has the required permissions.
- If using username/password, ensure the credentials are correct and the session is valid.
404 Not Found
Cause: The requested resource (project, workflow, etc.) does not exist or the URL is incorrect.
Resolution:
- Double-check the endpoint URL and resource identifiers.
- Ensure the project or workflow UID is correct and exists in the tenant.
- Confirm that the tenant domain is accurate.
403 Forbidden
Cause: The authenticated user does not have permission to perform the requested action.
Resolution:
- Check user roles and access levels in the tenant settings.
- Ensure the API key or token has sufficient privileges for the operation.
400 Bad Request
Cause: Malformed request body or missing required parameters.
Resolution:
- Validate the JSON payload structure.
- Refer to the API documentation for required fields and correct formats.
- Use tools like Postman to test and debug requests interactively.
500 Internal Server Error
Cause: Server-side issue or unexpected failure.
Resolution:
- Retry the request after a short delay.
- If the issue persists, contact IBM support with request details and logs.
Conclusion
Using webMethods Integration APIs transforms deployment from a manual, error-prone process into a fully automated pipeline. By leveraging APIs for exporting, importing, validating, and running sanity checks, organizations can enforce consistency, speed, and reliability in multi-tenant integration deployments and many other everyday task.
For platform teams and developers aiming to align integration with DevOps best practices, the Integration APIs are not just an alternative to the UI — they are the future of enterprise-grade automation.