> ## Documentation Index
> Fetch the complete documentation index at: https://rubie.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Blueprint

> Queue an asynchronous Blueprint run against a vaulted credential.

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

```bash theme={null}
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](/guides/blueprint-runs) for input routing, file
uploads, and polling guidance.


## OpenAPI

````yaml POST /blueprints/{blueprintKey}/trigger
openapi: 3.0.3
info:
  title: Rubie API
  version: 1.0.0
  description: >
    Collect end-user credentials through a Rubie-hosted form, then run Rubie

    Blueprints against them asynchronously.


    This API is deliberately thin. Rubie does not model your domain: what a

    Blueprint accepts as input, what it does with a connected system, and what
    it

    produces are all defined by that Blueprint's configuration. The endpoints

    below are the transport around it.


    All endpoints require bearer authentication. Responses use opaque prefixed
    IDs

    (`cred_`, `sess_`, `ecs_`, `strat_`, `run_`, `bp_`), snake_case fields, and
    a

    single top-level error envelope — never a `success` wrapper.
servers:
  - url: https://app.rubiehq.com/api/v1
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Credential Sessions
    description: Start and poll Rubie-hosted credential collection flows.
  - name: Embedded Credential Sessions
    description: Embed a Blueprint picker and credential capture flow in your product.
  - name: Credentials
    description: Revoke vaulted credentials.
  - name: Blueprints
    description: Trigger a Rubie Blueprint run.
  - name: Blueprint Runs
    description: Poll run status and retrieve completed outputs.
paths:
  /blueprints/{blueprintKey}/trigger:
    post:
      tags:
        - Blueprints
      summary: Trigger a Blueprint run
      description: >
        Queues one Rubie Blueprint run and returns 202 immediately with an
        opaque run id. Runs are asynchronous — poll run status every 2–5 seconds
        rather than holding the request open.


        Send `application/json` for structured payloads, or
        `multipart/form-data` when an INPUT node expects a file (CSV, XLSX,
        JSON). The routing rules for top-level keys are identical in both
        encodings.


        Use a stable `Idempotency-Key` — typically the id of the record in your
        system that triggered this run — so network retries cannot start
        duplicate runs.
      operationId: triggerBlueprint
      parameters:
        - name: blueprintKey
          in: path
          required: true
          schema:
            type: string
          description: The Blueprint's trigger key, from the Rubie dashboard.
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerBlueprintRequest'
          multipart/form-data:
            schema:
              type: object
              required:
                - credential_id
              additionalProperties: true
              description: >
                Same key routing as the JSON body. A part whose name matches an
                INPUT node `refKey` may carry a file or an inline string; string
                parts matching a configured metadata item are stored as run
                metadata.
              properties:
                credential_id:
                  type: string
                run_name:
                  type: string
      responses:
        '202':
          description: Run queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerBlueprintResponse'
              example:
                id: run_MQ
                run_key: 550e8400-e29b-41d4-a716-446655440000
                status: queued
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: >
        Unique key for safely retrying mutating requests. Matching key + body
        replays the original response for 24 hours. Matching key + different
        body returns 409 conflict.
  schemas:
    TriggerBlueprintRequest:
      type: object
      required:
        - credential_id
      additionalProperties: true
      description: >
        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
        `refKey`s and metadata items, or read them off the Blueprint canvas.
      properties:
        credential_id:
          type: string
          example: cred_NDc
          description: >
            Opaque credential id from a completed credential session. Accepts a
            single id or a comma-separated list; `credential_ids` is an accepted
            alias.
        run_name:
          type: string
          maxLength: 256
          description: Optional display name for the run, shown in the Rubie dashboard.
      example:
        credential_id: cred_NDc
        run_name: Nightly sync — Acme
        records:
          - external_id: '1042'
            name: Acme Corp
        source_system: acme-prod
    TriggerBlueprintResponse:
      type: object
      required:
        - id
        - run_key
        - status
      properties:
        id:
          type: string
          example: run_MQ
        run_key:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - type
        - message
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - authorization_error
            - not_found
            - validation_error
            - conflict
            - rate_limit_exceeded
            - internal_error
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        code:
          type: string
          nullable: true
        field:
          type: string
          nullable: true
  responses:
    ValidationError:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: API key is not authorized for this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found in this account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Request conflicts with the current resource state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: Your Rubie API key as a bearer token.

````