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

# Queue a Workflow Run

> Queue the latest published workflow version for background execution. Use the returned run_id to poll run status.



## OpenAPI

````yaml post /external/workflows/{group_id}/runs
openapi: 3.1.0
info:
  title: Shieldbase External API
  description: Public API for Shieldbase AI integration
  version: 1.0.0
servers:
  - url: https://api.shieldbase.ai
    description: Production
  - url: http://localhost:8000
    description: Development
security:
  - ClientID: []
    APIKey: []
    Secret: []
paths:
  /external/workflows/{group_id}/runs:
    post:
      tags:
        - Workflows
      summary: Queue a Workflow Run
      description: >-
        Queue the latest published workflow version for background execution.
        Use the returned run_id to poll run status.
      parameters:
        - $ref: '#/components/parameters/TenantID'
        - name: group_id
          in: path
          required: true
          description: Stable group_id from GET /external/workflows
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                run_id:
                  type: string
                  description: >-
                    Optional caller-provided run ID; generated by the server
                    when omitted
                executor_timezone:
                  type: integer
                  default: 0
                  description: Executor timezone offset in minutes
                external_user:
                  type: object
                  description: >-
                    External caller metadata only; it does not authenticate or
                    impersonate a tenant user
                  properties:
                    id:
                      type: string
                    email:
                      type: string
                    name:
                      type: string
                inputs:
                  type: object
                  properties:
                    form_inputs:
                      type: object
                      additionalProperties: true
                      description: Values keyed by active step ID or workflow_step_group_id
                    file_urls:
                      type: object
                      additionalProperties: true
                      description: >-
                        URLs keyed by active step ID or workflow_step_group_id;
                        each value can be a URL, URL array, or field-name to URL
                        map
            example:
              executor_timezone: 420
              external_user:
                id: partner-user-123
                email: user@example.com
                name: Example User
              inputs:
                form_inputs:
                  stable-step-group-id:
                    customer_name: Example Corp
                file_urls:
                  file-step-group-id:
                    - https://files.example.com/customer-doc.pdf
      responses:
        '200':
          description: Workflow run queued for background execution
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      run_id:
                        type: string
                      queue_id:
                        type: string
                      status:
                        type: string
                        example: queued
                      queue_status:
                        type: string
                        example: pending
                      group_id:
                        type: string
                      workflow_id:
                        type: string
                        description: Published workflow version selected for this run
                      current_step_id:
                        type: string
                      external_user:
                        type:
                          - object
                          - 'null'
        '400':
          description: Invalid workflow or input payload
        '403':
          description: Invalid credentials or workflow access denied
        '404':
          description: No active published workflow found
components:
  parameters:
    TenantID:
      name: X-Tenant-ID
      in: header
      required: false
      description: >-
        Optional tenant selector for multitenant accounts. The API key owner
        must have access to the selected tenant.
      schema:
        type: string
  securitySchemes:
    ClientID:
      type: apiKey
      in: header
      name: X-Client-ID
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
    Secret:
      type: apiKey
      in: header
      name: X-Secret

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.