Skip to main content
The blueprint.execute procedure runs a blueprint synchronously via the iBlueprint runner service and returns the result once execution completes. This is the fastest path for short-lived blueprints where you need the output inline. For long-running blueprints, use execution.executeBlueprintWithLogging instead, which logs progress to the database so you can poll for status with execution.getExecutionStatus.

​
Request

Procedure type: mutation (HTTP POST) Endpoint: 
POST https://api.iblueprint.ai/api/trpc/blueprint.execute
Content-Type: application/json
Body shape: 
{ "json": { ...parameters... } }

​
Parameters

​
json.id
string
required
UUID of the blueprint to execute. You must have access to the blueprint (owner, collaborator, org member, or the blueprint is public).
​
json.variables
object
Key-value map of runtime variables to inject into the blueprint. Nodes reference variables using {{variable_name}} syntax in their configuration. Defaults to an empty object if omitted.
{ "email_body": "Hi team, see attached report..." }

​
Response

​
success
boolean
true if the runner accepted and completed the execution.
​
executionId
string
Unique ID for this execution run, in the format exec_{timestamp}_{random}.
​
result
object
The raw output returned by the runner service. Shape varies by blueprint node configuration.

​
Examples

curl -X POST "https://api.iblueprint.ai/api/trpc/blueprint.execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "variables": {
        "email_body": "Hi team, please review the attached quarterly report.",
        "tone": "formal"
      }
    }
  }'

const response = await fetch(
  'https://api.iblueprint.ai/api/trpc/blueprint.execute',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      json: {
        id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
        variables: {
          email_body: 'Hi team, please review the attached quarterly report.',
          tone: 'formal',
        },
      },
    }),
  }
);

const { result } = await response.json();
const { success, executionId, result: runResult } = result.data.json;
console.log('Execution ID:', executionId);
console.log('Output:', runResult);

​
Sample response

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "executionId": "exec_1733050800000_a3b7z",
        "result": {
          "summary": "The team is requested to review the quarterly report attached to the email.",
          "steps": [...]
        }
      }
    }
  }
}

​
Asynchronous execution with logging

For blueprints that may take more than a few seconds, use execution.executeBlueprintWithLogging. This procedure writes step-level progress to the database as execution proceeds. You can then poll execution.getExecutionStatus with the returned executionId until status is completed or failed. 
# Start async execution
curl -X POST "https://api.iblueprint.ai/api/trpc/execution.executeBlueprintWithLogging" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "nodes": [...],
      "options": { "blueprintId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
    }
  }'

# Then poll status
curl -G "https://api.iblueprint.ai/api/trpc/execution.getExecutionStatus" \
  --data-urlencode 'input={"json":{"executionId":"exec_1733050800000_a3b7z"}}' \
  -H "Authorization: Bearer YOUR_API_KEY"
See Execution Status for the full polling guide.

​
Error handling

If the blueprint has no nodes, or if the runner service is unavailable, the API returns an error: 
{
  "error": {
    "json": {
      "message": "Blueprint has no nodes to execute",
      "code": -32600,
      "data": { "code": "BAD_REQUEST", "httpStatus": 400 }
    }
  }
}