Trigger Blueprint

Queue an asynchronous Blueprint run against a vaulted credential.

POST /blueprints/{blueprintKey}/trigger

Trigger a Blueprint run

cURL

curl --request POST \
  --url https://app.rubiehq.com/api/v1/blueprints/{blueprintKey}/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "credential_id": "cred_NDc",
  "run_name": "Nightly sync — Acme",
  "records": [
    {
      "external_id": "1042",
      "name": "Acme Corp"
    }
  ],
  "source_system": "acme-prod"
}
'

202

{
  "id": "run_MQ",
  "run_key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Queues one run and returns 202 immediately with an opaque run id. Poll GET /blueprint-runs/{runId}/status until a terminal state, then call GET /blueprint-runs/{runId}/results to retrieve completed outputs.

curl -s "$RUBIE_API_URL/api/v1/blueprints/$BLUEPRINT_KEY/trigger" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-acme-2026-07-31" \
  -d '{
    "credential_id": "cred_...",
    "run_name": "Nightly sync — Acme",
    "records": [{ "external_id": "1042", "name": "Acme Corp" }],
    "source_system": "acme-prod"
  }'

Request body routing

Only credential_id and run_name are reserved. Every other top-level key is matched by name against the Blueprint:

Key matches…	What happens
An INPUT node’s refKey	Value becomes that node’s input
A configured metadata item	Stored as run metadata (coerced to a string)
Neither	Ignored (including misspellings)

Send application/json for structured payloads, or multipart/form-data when an INPUT node expects a file. Routing rules are the same in both encodings.

Notes

• blueprintKey comes from Rubie / the dashboard — treat it as an opaque string.
• Prefer a stable Idempotency-Key (for example the id of the record in your system that triggered the run) so retries cannot start duplicates.
• A Blueprint may require specific metadata items; omitting a required one returns 400.

See Triggering Blueprint runs for input routing, file uploads, and polling guidance.

Authorizations

Authorization · string · header · required

Your Rubie API key as a bearer token.

Headers

Idempotency-Key · string

Unique key for safely retrying mutating requests. Matching key + body replays the original response for 24 hours. Matching key + different body returns 409 conflict.

Path Parameters

blueprintKey · string · required

The Blueprint's trigger key, from the Rubie dashboard.

Body

application/jsonmultipart/form-data

Only credential_id and run_name are reserved. Every other top-level key is routed by name, against the Blueprint's own configuration:

• If the key matches the refKey of an INPUT node, its value becomes that node's input payload. Objects and arrays are sent as JSON; strings are passed through as-is.

• If the key matches a metadata item configured on the Blueprint, it is stored as run metadata (coerced to a string) and shown on the run in the Rubie dashboard. Use these for correlation ids from your own system.

• If the key matches neither, it is ignored.

A Blueprint may mark a metadata item as required, in which case omitting it returns 400. Ask your Rubie contact for the Blueprint's input refKeys and metadata items, or read them off the Blueprint canvas.

credential_id · string · required

Opaque credential id from a completed credential session. Accepts a single id or a comma-separated list; credential_ids is an accepted alias.

Example:

"cred_NDc"

run_name · string

Optional display name for the run, shown in the Rubie dashboard.

Maximum string length: 256

Response

202

application/json

Run queued

id · string · required

Example:

"run_MQ"

run_key · string<uuid> · required

status · enum<string> · required

Available options: queued