Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory.
Inspect skipped and inputValidationErrors for edits that did not apply. Deferred edges apply when their targets exist; do not resubmit them. With atomic=true, declined operations or dropped inputs return 409 (OPERATIONS_NOT_APPLIED) without saving. Use returned mintedBlockIds in later requests. dryRun=true evaluates without saving, auditing, or notifying. Workspace API keys return 403; use a personal API key or scoped OAuth token.
OAuth scope: api:write.
/api/v2/workflows/{workflowId}/operationsYour Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.
In: header
Request examples use an API key. For OAuth, replace the X-API-Key header with Authorization: Bearer YOUR_ACCESS_TOKEN.
curl -X POST "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/operations" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operations": [ { "operation_type": "add", "block_id": "agent-1", "params": { "type": "agent", "name": "Triage", "inputs": { "tools": [ { "type": "cloudwatch", "operation": "describe_alarm_history", "usageControl": "auto", "params": {} } ] } } } ] }'{
"data": {
"id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
"applied": 1,
"skipped": [],
"deferred": [],
"inputValidationErrors": [],
"mintedBlockIds": {
"agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77"
},
"lint": {
"sources": [],
"sinks": [],
"orphanBlocks": [],
"emptyOutgoingPorts": [],
"invalidBranchPorts": [],
"invalidConnectionTargets": [],
"fieldIssues": [
{
"blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77",
"blockName": "Triage",
"blockType": "agent",
"missingRequiredFields": [
"systemPrompt"
],
"inactiveModeValues": []
}
],
"unresolvedReferences": [],
"tableFieldIssues": [],
"notes": []
},
"warnings": [],
"needsRedeployment": true,
"dryRun": false
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "Insufficient workspace permissions",
"details": {
"code": "INSUFFICIENT_WORKSPACE_ROLE"
}
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "The request conflicts with current resource state"
}
}{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body is too large"
}
}{
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Request body must be sent as application/json"
}
}{
"error": {
"code": "LOCKED",
"message": "Workflow is locked"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "API rate limit exceeded",
"details": {
"retryAfter": "2026-01-01T00:00:30.000Z"
}
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "Service temporarily unavailable"
}
}Path parameters
Unique workflow identifier.
1 <= lengthQuery parameters
Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (409) as a committed write. needsRedeployment describes the pre-write state. For semantic operations, mintedBlockIds is empty; previewBlockIds contains provisional IDs with a warning, since committing mints new IDs.
Request body
application/json
A batch of semantic edits against a workflow graph.
TypeScript definitions
Use the request body type in TypeScript.
Response body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json