Triggering Blueprint Runs

How inputs are routed, how to send files, and how to retrieve completed run results.

A Blueprint is a workflow you and Rubie configure together: which system to log into, what to extract or write, how to map and validate the data. The API around it is deliberately thin — you hand Rubie a credential and some inputs, and get back a run to poll.

Because the workflow lives in configuration rather than in this API, the request body is defined by your Blueprint, not by a fixed schema. This guide explains the routing rules that make that work.

Triggering a run

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"
  }'

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

202 means queued, not done. The run executes asynchronously — see Polling below.

How top-level keys are routed

Only two keys are reserved. Everything else is matched by name against your Blueprint’s configuration:

Key	Routed to
credential_id	The vaulted credential the run authenticates with
run_name	Display name for the run in the Rubie dashboard
Matches an INPUT node’s refKey	That node’s input payload
Matches a configured metadata item	Run metadata, coerced to a string
Matches nothing	Ignored

That last row is the one to watch: a misspelled input key is silently dropped, not rejected. If a run behaves as though a node received no data, check the key against the Blueprint’s refKey first.

Your Rubie contact can give you the Blueprint’s INPUT refKeys and its configured metadata items, or you can read them off the Blueprint canvas in the dashboard.

Inputs

In the example above, records is the refKey of an INPUT node. Objects and arrays are serialized to JSON for the node; strings are passed through untouched.

Metadata

source_system in the example is a metadata item — useful for stamping a run with correlation ids from your own system (a tenant id, a job id, the record that triggered the run) so your team can trace it later from the dashboard.

Metadata items must be configured on the Blueprint to be persisted. If one is marked required and you omit it, the trigger returns 400.

Credentials

credential_id accepts a single id or a comma-separated list, and credential_ids is an accepted alias. Most Blueprints need exactly one; pass several when a workflow touches more than one system.

The credential must belong to the same account as the API key, and the API key must be authorized for the Blueprint.

Sending files

When an INPUT node expects a file rather than inline data, send multipart/form-data instead. The routing rules are identical — the part name is the key.

curl -s "$RUBIE_API_URL/api/v1/blueprints/$BLUEPRINT_KEY/trigger" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Idempotency-Key: import-acme-2026-07-31" \
  -F "credential_id=cred_..." \
  -F "run_name=Acme import" \
  -F "records=@customers.csv"

Parts matching an input refKey may carry either a file or an inline string, so you can mix uploaded files and inline JSON in the same request.

Polling a run

Poll GET /blueprint-runs/{runId}/status every 2–5 seconds. The endpoint accepts either the opaque run_... id or the UUID run_key from the trigger response.

curl -s "$RUBIE_API_URL/api/v1/blueprint-runs/run_.../status" \
  -H "Authorization: Bearer $RUBIE_API_KEY"

{
  "id": "run_...",
  "run_key": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress_step": "running",
  "created_at": "2026-07-31T00:00:00.000Z",
  "started_at": "2026-07-31T00:00:04.000Z",
  "ended_at": null,
  "error": null,
  "blueprint_id": "bp_..."
}

Status and progress step

status is the coarse lifecycle state you branch on. progress_step is a finer projection of the same run, useful for showing the user what’s happening.

status	Terminal?	progress_step values
queued	No	queued, authenticating
running	No	running, awaiting_review
completed	Yes	completed
failed	Yes	failed
cancelled	Yes	cancelled

authenticating means the run is logging into the target system, which is where invalid credentials surface. awaiting_review means a human review gate in the Blueprint is holding the run — it’s still running from your side, and will proceed once someone acts on it in the dashboard.

Treat both fields as open string sets. Finer, Blueprint-defined milestones will be added to progress_step later. Branch on the values you know and fall through to a neutral “in progress” state for anything else.

This endpoint is a projection, not the run

The status response deliberately contains no run inputs, outputs, file URLs, or raw error strings — only lifecycle facts. That makes it safe to poll from systems handling regulated or sensitive data, since nothing the run touched can leak through it.

Retrieve outputs separately after the run reaches completed; see Fetching results.

Fetching results

Call GET /blueprint-runs/{runId}/results only after status is completed. Like the status endpoint, it accepts either the opaque run_... id or the UUID run_key from the trigger response.

To return records directly in JSON:

curl -s "$RUBIE_API_URL/api/v1/blueprint-runs/run_.../results?deliveryMethod=direct" \
  -H "Authorization: Bearer $RUBIE_API_KEY"

{
  "dataDeliveryMethod": "direct",
  "results": {
    "customers": {
      "totalRecords": 1,
      "records": [
        {
          "data": { "external_id": "1042", "name": "Acme Corp" },
          "errors": [],
          "isValid": true
        }
      ]
    }
  },
  "executionMetadata": {
    "runKey": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": { "source_system": "acme-prod" },
    "timings": {
      "executionBeganAt": "2026-07-31T00:00:04.000Z",
      "executionCompletedAt": "2026-07-31T00:02:00.000Z"
    }
  }
}

results is keyed by Blueprint output node reference key. A node with multiple output handles uses keys such as node_ref.handle_key. Each direct record contains its output data, validation errors, and isValid flag.

For large datasets, omit the query parameter or use deliveryMethod=presigned_url:

{
  "dataDeliveryMethod": "presigned_url",
  "results": {
    "customers": "https://temporary-download-url..."
  },
  "executionMetadata": { "runKey": "...", "metadata": {}, "timings": {} }
}

The URLs contain Brotli-compressed JSON, expire after two hours, and should be downloaded promptly. Direct delivery automatically falls back to presigned URLs when the estimated response is 5 MB or larger. Always inspect the returned dataDeliveryMethod rather than assuming it matches the request.

The endpoint returns 409 while a run is incomplete and 400 after its data has been purged.

Failures

When status is failed, error is populated:

{
  "code": "execution_failed",
  "message": "The run failed. Retry the request, or contact support if the issue persists."
}

Today every failed run reports execution_failed. Specific causes — expired credentials, a missing template in the target system, a validation failure — are not yet distinguishable through this endpoint; your Rubie team can inspect the run in the dashboard. Surface a retry action plus a path back to your reconnect flow, and treat error.code as an open string set so Blueprint-defined codes can be added later without breaking your client. See Errors.

Idempotency

Trigger requests should always carry an Idempotency-Key, keyed on the thing that caused the run — a record id, a job id, a date-scoped sync key. A retried request with the same key and body replays the original 202 instead of starting a second run. Same key with a different body returns 409. See Idempotency.

Next

• Hosted credential collection — where cred_... comes from
• Errors — the error envelope and validation codes
• Get Blueprint run results — response schema and delivery modes
• Identifiers — run_ ids versus run_key