How to execute via API
What this feature does
The Opus Execution Server (OES) provides REST API endpoints for executing published workflows and decisions from external systems. Separate endpoints are available for staging and production environments.
Scope: This guide covers generating access tokens, constructing API requests, and executing workflows and decisions via API. It does not cover building or publishing (refer to How to publish and release).
Who this applies to
- Audience: Developers and integrators calling Opus workflows and decisions from external systems
- Access required: Administrator role (for generating access tokens); any role can execute if they have the token
- Assumed knowledge: Your workflow or decision is published. Refer to How to publish and release.
Steps
Step 1: Generate an access token
All API requests require a valid access token. Only administrators can generate tokens.
- Navigate to the project’s Access Token page.
- Select Generate Token for the target environment (staging or production).
- Copy the token. Store it securely — it is shown only once.
Step 2: Get the endpoint URL
The endpoint URL is available in the trigger node settings of your workflow or decision.
- Open the workflow or decision in the editor.
- Select the trigger node and open its settings.
- Copy the staging or production endpoint URL.
Endpoint URL patterns:
| Entity | Staging | Production |
|---|---|---|
| Workflow | https://lite.staging.oes.opus.gov.sg/api/workflow/<namespace>/<project>/<entity>?branch=main |
https://lite.production.oes.opus.gov.sg/api/workflow/<namespace>/<project>/<entity>?branch=main |
| Decision | https://lite.staging.oes.opus.gov.sg/api/decision/<namespace>/<project>/<entity>?branch=main |
https://lite.production.oes.opus.gov.sg/api/decision/<namespace>/<project>/<entity>?branch=main |
The endpoint path varies by trigger node type. Always copy the URL from the trigger node settings — do not construct it manually.
Step 3: Make the API call
Send a POST request with the access token and a JSON payload.
curl -X POST "<endpoint-url>" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"applicantName": "Jane Doe", "amount": 5000}'The response includes the execution result. For workflows, the response contains the workflow execution ID for monitoring.
Constraints and limitations
| Constraint | Detail |
|---|---|
| Draft versions | Cannot be executed — must be published first |
| Access token scope | Tokens are per-project and per-environment (staging or production) |
| Authentication | Bearer token in the Authorization header |
| Payload size | 10 MB maximum |
Related features
- How to publish and release — publish workflows and decisions before API execution.
- Limits and constraints — payload size, retry limits, and timeout values.
- Service levels and network — network requirements and IP whitelisting for external systems calling Opus.
