Quickstart

Every Rubie integration is two loops with different lifetimes:

Connect — once per user, per system. Your user hands over their credentials through a form Rubie hosts, and you get back an id to store against them.
Run — as often as you need. You trigger a Blueprint with that id and poll until it finishes, then fetch its outputs.

What you’ll need

Value	Where it comes from	How many you’ll have
API key	Your Rubie dashboard	One or more per account
`strategy_id`	Provided by Rubie	One per system your users connect
Blueprint key	Provided by Rubie	One per workflow

The API key is a secret, so keep it in your server-side environment or secret manager:

export RUBIE_API_KEY="sk_..."
export RUBIE_API_URL="https://app.rubiehq.com"

Strategy ids and Blueprint keys are non-secret configuration. For a single integration, constants are the simplest option. If your application later supports several source systems or workflows, move them into configuration or separate lookup tables. They are not fixed pairs: one strategy can be reused by several Blueprints, and a Blueprint can require more than one strategy.

const strategyId = "strat_...";
const blueprintKey = "your-blueprint-key";

const apiKey = process.env.RUBIE_API_KEY;
const baseUrl = process.env.RUBIE_API_URL ?? "https://app.rubiehq.com";

async function rubieJson(url, init = {}) {
  const response = await fetch(url, init);
  const body = await response.json().catch(() => null);

  if (!response.ok) {
    throw new Error(
      body?.error?.message ?? `Rubie request failed (${response.status})`,
    );
  }

  return body;
}

API keys are account-scoped and every endpoint here is server-to-server, so keys must never reach a browser. See Authentication.

Part 1 — Connect an account

Do this once, when a user first connects a system. The credentials go straight from your user to Rubie’s vault — they never touch your servers.

Create a credential session

strategy_id tells Rubie which system the user is connecting, so it renders the right fields on the form. return_url sends them back to your app when they’re done. Ask Rubie to allowlist its exact origin on the account that owns the API key making this request, then open the returned hosted_url in the same tab or a new one.

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/credential-sessions" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connect-integration-123" \
  -d '{
    "strategy_id": "strat_...",
    "name": "Production source account",
    "return_url": "https://app.example.com/integrations/rubie/connected"
  }'
# → { "id": "sess_...", "status": "pending", "hosted_url": "...", "return_url": "...", "credential_id": null }

const session = await rubieJson(`${baseUrl}/api/v1/credential-sessions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "connect-integration-123",
  },
  body: JSON.stringify({
    strategy_id: strategyId,
    name: "Production source account",
    return_url: "https://app.example.com/integrations/rubie/connected",
  }),
});

// Open session.hosted_url for the user

name is just a label for your team in the Rubie dashboard. Something that identifies the connection is a good choice.

Confirm the session, then store the credential id

After collection, Rubie redirects to your return_url with the session id:https://app.example.com/integrations/rubie/connected?session_id=sess_...Read session_id from the query string and confirm the session from your backend before saving credential_id:

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/credential-sessions/sess_..." \
  -H "Authorization: Bearer $RUBIE_API_KEY"
# → { "status": "completed", "credential_id": "cred_...", ... }

const sessionId = requestUrl.searchParams.get("session_id");

const current = await rubieJson(
  `${baseUrl}/api/v1/credential-sessions/${sessionId}`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);

if (current.status === "completed") {
  await db.saveIntegrationCredential(current.credential_id); // "cred_..."
}

When status is completed, credential_id is populated. Save it in your application’s integration settings. Rubie already stores the underlying credential under the account associated with your API key; your application stores only this opaque id so it can select the connection on future runs.If your application supports multiple connections, associate each credential_id with the corresponding workspace or integration. Branch on completed and expired; if the status is anything else, poll briefly until it settles. That id is now good for as many runs as you like.

Part 2 — Run a Blueprint

Now that you have a cred_..., trigger a run whenever you need work done in that system — on a schedule, on a webhook, or from a button in your UI.

Trigger the run

Pass the stored credential id. You’ll get 202 back: the run is queued, not finished.

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/blueprints/your-blueprint-key/trigger" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: integration-run-2026-07-31" \
  -d '{
    "credential_id": "cred_...",
    "run_name": "On-demand integration run"
  }'
# → 202 { "id": "run_...", "run_key": "...", "status": "queued" }

const credentialId = await db.getIntegrationCredential();

const run = await rubieJson(
  `${baseUrl}/api/v1/blueprints/${blueprintKey}/trigger`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "integration-run-2026-07-31",
    },
    body: JSON.stringify({
      credential_id: credentialId,
      run_name: "On-demand integration run",
    }),
  },
);
// run.id → "run_..."

Poll until it finishes

Poll every 2–5 seconds until status is completed, failed, or cancelled. Don’t block a user-facing request on it.

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/blueprint-runs/run_.../status" \
  -H "Authorization: Bearer $RUBIE_API_KEY"
# → { "status": "completed", "progress_step": "completed", "error": null, ... }

const runStatus = await rubieJson(
  `${baseUrl}/api/v1/blueprint-runs/${run.id}/status`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);

// runStatus.status, runStatus.progress_step, runStatus.error?.code

On failed, error.code is execution_failed — offer a retry. A network retry of the original trigger request should reuse its Idempotency-Key, but a user-initiated retry after a terminal failure is a new logical operation and must use a new key. Otherwise Rubie replays the original run response instead of creating another run.This endpoint returns lifecycle facts only, never run inputs, outputs, or file URLs, so it’s safe to poll from systems handling regulated data.

Fetch the results

After the status is completed, fetch the Blueprint outputs. Use direct delivery when you want records in the response body:

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/blueprint-runs/run_.../results?deliveryMethod=direct" \
  -H "Authorization: Bearer $RUBIE_API_KEY"
# → { "dataDeliveryMethod": "direct", "results": { ... }, "executionMetadata": { ... } }

const output = await rubieJson(
  `${baseUrl}/api/v1/blueprint-runs/${run.id}/results?deliveryMethod=direct`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);

if (output.dataDeliveryMethod === "direct") {
  for (const [outputKey, result] of Object.entries(output.results)) {
    console.log(outputKey, result.totalRecords, result.records);
  }
} else {
  for (const [outputKey, downloadUrl] of Object.entries(output.results)) {
    const response = await fetch(downloadUrl);
    if (!response.ok) throw new Error(`Result download failed (${response.status})`);
    const result = await response.json();
    console.log(outputKey, result.totalRecords, result.records);
  }
}

Direct responses contain each output’s records. For larger results, request deliveryMethod=presigned_url (the default) and download the temporary URLs in results. Rubie automatically switches a direct request to presigned URL delivery when the estimated payload is 5 MB or larger, so always branch on the returned dataDeliveryMethod.

Disconnecting

When a user disconnects a system, revoke the credential. This is a hard delete: the vaulted secrets are destroyed and the cred_... stops resolving, so drop your stored mapping at the same time.

curl --fail-with-body -sS "$RUBIE_API_URL/api/v1/credentials/cred_..." \
  -X DELETE \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Idempotency-Key: disconnect-user-123"
# → 204

Hosted credential collection — session lifecycle, embedding, and reconnect flows
Embedded Credential Capture — let users choose a Blueprint and connect inside an iframe
Triggering Blueprint runs — input routing, file uploads, polling, and results in depth
Idempotency — why every example above carries an Idempotency-Key
Auth strategies — what sits behind a strategy_id, if you’re curious

Start Here

Concepts

Guides

What you’ll need

Part 1 — Connect an account

Part 2 — Run a Blueprint

Disconnecting

Next

​What you’ll need

​Part 1 — Connect an account

​Part 2 — Run a Blueprint

​Disconnecting

​Next

What you’ll need

Part 1 — Connect an account

Part 2 — Run a Blueprint

Disconnecting

Next