Girard AI - AI Automation Platform

openapi: 3.0.3 info: title: Girard API description: | The Girard API provides programmatic access to AI workflow automation capabilities.

## Authentication

All API requests require authentication using an API key. Include your API key in the
`Authorization` header using the Bearer scheme:

```
Authorization: Bearer your-api-key
```

You can create API keys in the [Dashboard](/dashboard/api-keys).

## Rate Limiting

API requests are rate-limited based on your subscription plan. The following headers
are included in all responses:

- `X-RateLimit-Limit`: Maximum requests allowed per window
- `X-RateLimit-Remaining`: Requests remaining in current window
- `X-RateLimit-Reset`: Unix timestamp when the window resets

## Error Handling

All errors follow a consistent format with structured error codes for programmatic handling.

version: 1.0.0 contact: name: Girard Support email: support@girardai.com url: https://www.girardai.com license: name: Proprietary url: https://www.girardai.com/terms

servers:

url: https://www.girardai.com/api/v1 description: Production
url: http://localhost:3000/api/v1 description: Local Development

tags:

name: Workflows description: Create, manage, and execute AI workflows
name: Runs description: Monitor workflow execution history

security:

BearerAuth: []

paths: /workflows: get: tags: - Workflows summary: List workflows description: Returns a paginated list of all workflows owned by the authenticated user. operationId: listWorkflows parameters: - name: active in: query description: Filter by active status schema: type: boolean - name: limit in: query description: Maximum number of workflows to return (1-100) schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query description: Number of workflows to skip for pagination schema: type: integer minimum: 0 default: 0 responses: '200': description: Successful response headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/WorkflowListResponse' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

post:
  tags:
    - Workflows
  summary: Create workflow
  description: Creates a new workflow with the specified configuration.
  operationId: createWorkflow
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WorkflowCreateRequest'
  responses:
    '201':
      description: Workflow created successfully
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkflowCreateResponse'
    '400':
      $ref: '#/components/responses/ValidationError'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '429':
      $ref: '#/components/responses/RateLimitExceeded'
    '500':
      $ref: '#/components/responses/InternalError'

/workflows/{id}: get: tags: - Workflows summary: Get workflow description: Returns detailed information about a specific workflow including its steps and configuration. operationId: getWorkflow parameters: - $ref: '#/components/parameters/WorkflowId' responses: '200': description: Successful response headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/WorkflowDetailResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/WorkflowNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

patch:
  tags:
    - Workflows
  summary: Update workflow
  description: Updates an existing workflow. Only provided fields will be updated.
  operationId: updateWorkflow
  parameters:
    - $ref: '#/components/parameters/WorkflowId'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WorkflowUpdateRequest'
  responses:
    '200':
      description: Workflow updated successfully
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkflowUpdateResponse'
    '400':
      $ref: '#/components/responses/ValidationError'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/WorkflowNotFound'
    '429':
      $ref: '#/components/responses/RateLimitExceeded'
    '500':
      $ref: '#/components/responses/InternalError'

delete:
  tags:
    - Workflows
  summary: Delete workflow
  description: Permanently deletes a workflow and all associated run history.
  operationId: deleteWorkflow
  parameters:
    - $ref: '#/components/parameters/WorkflowId'
  responses:
    '200':
      description: Workflow deleted successfully
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: true
              data:
                type: object
                properties:
                  deleted:
                    type: boolean
                    example: true
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/WorkflowNotFound'
    '429':
      $ref: '#/components/responses/RateLimitExceeded'
    '500':
      $ref: '#/components/responses/InternalError'

/workflows/{id}/execute: post: tags: - Workflows summary: Execute workflow description: | Executes a workflow with optional input data and variables.

    The workflow must be active to be executed. Input and variables can be used
    to customize the workflow execution by replacing placeholders in prompts:

    - `{{input}}` - Replaced with the input value
    - `{{variableName}}` - Replaced with the corresponding variable value

  operationId: executeWorkflow
  parameters:
    - $ref: '#/components/parameters/WorkflowId'
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WorkflowExecuteRequest'
  responses:
    '200':
      description: Workflow executed successfully
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkflowExecuteResponse'
    '400':
      $ref: '#/components/responses/WorkflowInactive'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/WorkflowNotFound'
    '429':
      $ref: '#/components/responses/RateLimitExceeded'
    '500':
      $ref: '#/components/responses/ExecutionError'

/workflows/{id}/runs: get: tags: - Runs summary: List workflow runs description: Returns a paginated list of execution history for a specific workflow. operationId: listWorkflowRuns parameters: - $ref: '#/components/parameters/WorkflowId' - name: status in: query description: Filter by run status schema: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - name: limit in: query description: Maximum number of runs to return (1-100) schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query description: Number of runs to skip for pagination schema: type: integer minimum: 0 default: 0 responses: '200': description: Successful response headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/RunListResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/WorkflowNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

/runs/{id}: get: tags: - Runs summary: Get run details description: Returns detailed information about a specific workflow run including input, output, and execution metrics. operationId: getRun parameters: - name: id in: path required: true description: The unique identifier of the run schema: type: string format: uuid responses: '200': description: Successful response headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/RunDetailResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/RunNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: | API key authentication. Create keys at Dashboard.

    Example: `Authorization: Bearer girard_live_abc123...`

parameters: WorkflowId: name: id in: path required: true description: The unique identifier of the workflow schema: type: string format: uuid

headers: X-RateLimit-Limit: description: Maximum requests allowed per rate limit window schema: type: integer example: 1000 X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: integer example: 999 X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets schema: type: integer example: 1704067200 X-Request-ID: description: Unique identifier for the request (useful for debugging) schema: type: string format: uuid

schemas: # Request Schemas WorkflowCreateRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 100 description: Name of the workflow example: Content Generator description: type: string maxLength: 500 nullable: true description: Optional description of the workflow example: Generates blog content based on topic input steps: type: array description: Array of workflow steps items: $ref: '#/components/schemas/WorkflowStep' config: type: object description: Additional workflow configuration additionalProperties: true aiModel: type: string description: AI model to use for execution example: claude-sonnet-4-20250514 default: claude-sonnet-4-20250514 aiProvider: type: string enum: - ANTHROPIC - OPENAI - GOOGLE description: AI provider default: ANTHROPIC

WorkflowUpdateRequest:
  type: object
  properties:
    name:
      type: string
      minLength: 1
      maxLength: 100
      description: Updated name
    description:
      type: string
      maxLength: 500
      nullable: true
      description: Updated description
    steps:
      type: array
      description: Updated workflow steps
      items:
        $ref: '#/components/schemas/WorkflowStep'
    config:
      type: object
      description: Updated configuration
      additionalProperties: true
    aiModel:
      type: string
      description: Updated AI model
    aiProvider:
      type: string
      enum:
        - ANTHROPIC
        - OPENAI
        - GOOGLE
      description: Updated AI provider
    isActive:
      type: boolean
      description: Enable or disable the workflow

WorkflowExecuteRequest:
  type: object
  properties:
    input:
      description: Input data to pass to the workflow
      example: Write about artificial intelligence
    variables:
      type: object
      description: Key-value pairs for variable substitution in prompts
      additionalProperties:
        type: string
      example:
        tone: professional
        length: medium

WorkflowStep:
  type: object
  required:
    - id
    - type
  properties:
    id:
      type: string
      description: Unique step identifier
    type:
      type: string
      enum:
        - prompt
        - condition
        - transform
      description: Step type
    prompt:
      type: string
      description: Prompt template (for prompt steps). Use {{input}} and {{variableName}} for substitutions.
      example: "Write a {{length}} blog post about {{input}} with a {{tone}} tone."

# Response Schemas
WorkflowListResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      type: object
      properties:
        workflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'

WorkflowCreateResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      $ref: '#/components/schemas/WorkflowSummary'

WorkflowDetailResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      $ref: '#/components/schemas/WorkflowDetail'

WorkflowUpdateResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        isActive:
          type: boolean
        aiModel:
          type: string
        updatedAt:
          type: string
          format: date-time

WorkflowExecuteResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      type: object
      properties:
        runId:
          type: string
          format: uuid
          description: Unique identifier for this execution
        status:
          type: string
          enum:
            - COMPLETED
            - FAILED
          description: Execution status
        output:
          type: string
          description: Generated output from the workflow
        tokensUsed:
          type: integer
          description: Total tokens consumed during execution
        durationMs:
          type: integer
          description: Execution duration in milliseconds

RunListResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/RunSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'

RunDetailResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    data:
      $ref: '#/components/schemas/RunDetail'

# Shared Schemas
WorkflowSummary:
  type: object
  properties:
    id:
      type: string
      format: uuid
    name:
      type: string
    description:
      type: string
      nullable: true
    isActive:
      type: boolean
    totalRuns:
      type: integer
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time

WorkflowDetail:
  allOf:
    - $ref: '#/components/schemas/WorkflowSummary'
    - type: object
      properties:
        aiModel:
          type: string
        aiProvider:
          type: string
          enum:
            - ANTHROPIC
            - OPENAI
            - GOOGLE
        steps:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStep'
        config:
          type: object
          additionalProperties: true

RunSummary:
  type: object
  properties:
    id:
      type: string
      format: uuid
    status:
      type: string
      enum:
        - PENDING
        - RUNNING
        - COMPLETED
        - FAILED
    input:
      type: object
      nullable: true
    output:
      type: object
      nullable: true
    error:
      type: string
      nullable: true
    tokensUsed:
      type: integer
      nullable: true
    durationMs:
      type: integer
      nullable: true
    createdAt:
      type: string
      format: date-time

RunDetail:
  allOf:
    - $ref: '#/components/schemas/RunSummary'
    - type: object
      properties:
        workflowId:
          type: string
          format: uuid
        workflowName:
          type: string

Pagination:
  type: object
  properties:
    total:
      type: integer
      description: Total number of items
    limit:
      type: integer
      description: Items per page
    offset:
      type: integer
      description: Current offset
    hasMore:
      type: boolean
      description: Whether more items are available

# Error Schemas
ApiError:
  type: object
  required:
    - success
    - error
  properties:
    success:
      type: boolean
      example: false
    error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
        hint:
          type: string
          description: Suggestion for resolving the error
        requestId:
          type: string
          format: uuid
          description: Request ID for support reference

responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missing_key: summary: Missing API Key value: success: false error: code: missing_api_key message: API key is required. hint: Include your API key in the Authorization header as 'Bearer <key>'. invalid_key: summary: Invalid API Key value: success: false error: code: invalid_api_key message: The provided API key is invalid. hint: Check that your API key is correct and has not been revoked. expired_key: summary: Expired API Key value: success: false error: code: expired_api_key message: The API key has expired. hint: Generate a new API key in the dashboard.

ValidationError:
  description: Request validation failed
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: validation_error
          message: Request validation failed.
          details:
            errors:
              - path: name
                message: Name is required
          hint: Check the errors array for specific field issues.

WorkflowNotFound:
  description: Workflow not found
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: workflow_not_found
          message: Workflow not found.
          details:
            workflowId: 123e4567-e89b-12d3-a456-426614174000
          hint: Verify the workflow ID is correct and belongs to your account.

WorkflowInactive:
  description: Workflow is inactive
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: workflow_inactive
          message: This workflow is currently inactive.
          details:
            workflowId: 123e4567-e89b-12d3-a456-426614174000
          hint: Activate the workflow in the dashboard before executing.

RunNotFound:
  description: Run not found
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: run_not_found
          message: Run not found.
          details:
            runId: 123e4567-e89b-12d3-a456-426614174000
          hint: Verify the run ID is correct and belongs to your account.

RateLimitExceeded:
  description: Rate limit exceeded
  headers:
    X-RateLimit-Limit:
      $ref: '#/components/headers/X-RateLimit-Limit'
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 0
    X-RateLimit-Reset:
      $ref: '#/components/headers/X-RateLimit-Reset'
    Retry-After:
      description: Seconds until the rate limit resets
      schema:
        type: integer
        example: 60
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: rate_limit_exceeded
          message: Rate limit exceeded. Please try again later.
          details:
            limit: 1000
            resetAt: 1704067200
          hint: Wait for the rate limit window to reset or upgrade your plan.

ExecutionError:
  description: Workflow execution failed
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      examples:
        ai_error:
          summary: AI Provider Error
          value:
            success: false
            error:
              code: ai_provider_error
              message: The AI provider returned an error. Please try again.
              details:
                runId: 123e4567-e89b-12d3-a456-426614174000
              hint: This may be a temporary issue with the AI provider. Try again in a few moments.
        internal_error:
          summary: Internal Error
          value:
            success: false
            error:
              code: internal_error
              message: An error occurred while executing the workflow.
              details:
                runId: 123e4567-e89b-12d3-a456-426614174000
              hint: If this persists, please contact support.

InternalError:
  description: Internal server error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ApiError'
      example:
        success: false
        error:
          code: internal_error
          message: An unexpected error occurred.
          hint: If this persists, please contact support.

## Authentication All API requests require authentication using an API key. Include your API key in the `Authorization` header using the Bearer scheme: ``` Authorization: Bearer your-api-key ``` You can create API keys in the [Dashboard](/dashboard/api-keys). ## Rate Limiting API requests are rate-limited based on your subscription plan. The following headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed per window - `X-RateLimit-Remaining`: Requests remaining in current window - `X-RateLimit-Reset`: Unix timestamp when the window resets ## Error Handling All errors follow a consistent format with structured error codes for programmatic handling.

post: tags: - Workflows summary: Create workflow description: Creates a new workflow with the specified configuration. operationId: createWorkflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateRequest' responses: '201': description: Workflow created successfully headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

patch: tags: - Workflows summary: Update workflow description: Updates an existing workflow. Only provided fields will be updated. operationId: updateWorkflow parameters: - $ref: '#/components/parameters/WorkflowId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowUpdateRequest' responses: '200': description: Workflow updated successfully headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/WorkflowUpdateResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/WorkflowNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' delete: tags: - Workflows summary: Delete workflow description: Permanently deletes a workflow and all associated run history. operationId: deleteWorkflow parameters: - $ref: '#/components/parameters/WorkflowId' responses: '200': description: Workflow deleted successfully headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: deleted: type: boolean example: true '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/WorkflowNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError'

The workflow must be active to be executed. Input and variables can be used to customize the workflow execution by replacing placeholders in prompts: - `{{input}}` - Replaced with the input value - `{{variableName}}` - Replaced with the corresponding variable value operationId: executeWorkflow parameters: - $ref: '#/components/parameters/WorkflowId' requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkflowExecuteRequest' responses: '200': description: Workflow executed successfully headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/WorkflowExecuteResponse' '400': $ref: '#/components/responses/WorkflowInactive' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/WorkflowNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/ExecutionError'

WorkflowUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 100 description: Updated name description: type: string maxLength: 500 nullable: true description: Updated description steps: type: array description: Updated workflow steps items: $ref: '#/components/schemas/WorkflowStep' config: type: object description: Updated configuration additionalProperties: true aiModel: type: string description: Updated AI model aiProvider: type: string enum: - ANTHROPIC - OPENAI - GOOGLE description: Updated AI provider isActive: type: boolean description: Enable or disable the workflow WorkflowExecuteRequest: type: object properties: input: description: Input data to pass to the workflow example: Write about artificial intelligence variables: type: object description: Key-value pairs for variable substitution in prompts additionalProperties: type: string example: tone: professional length: medium WorkflowStep: type: object required: - id - type properties: id: type: string description: Unique step identifier type: type: string enum: - prompt - condition - transform description: Step type prompt: type: string description: Prompt template (for prompt steps). Use {{input}} and {{variableName}} for substitutions. example: "Write a {{length}} blog post about {{input}} with a {{tone}} tone." # Response Schemas WorkflowListResponse: type: object properties: success: type: boolean example: true data: type: object properties: workflows: type: array items: $ref: '#/components/schemas/WorkflowSummary' pagination: $ref: '#/components/schemas/Pagination' WorkflowCreateResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/WorkflowSummary' WorkflowDetailResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/WorkflowDetail' WorkflowUpdateResponse: type: object properties: success: type: boolean example: true data: type: object properties: id: type: string format: uuid name: type: string description: type: string nullable: true isActive: type: boolean aiModel: type: string updatedAt: type: string format: date-time WorkflowExecuteResponse: type: object properties: success: type: boolean example: true data: type: object properties: runId: type: string format: uuid description: Unique identifier for this execution status: type: string enum: - COMPLETED - FAILED description: Execution status output: type: string description: Generated output from the workflow tokensUsed: type: integer description: Total tokens consumed during execution durationMs: type: integer description: Execution duration in milliseconds RunListResponse: type: object properties: success: type: boolean example: true data: type: object properties: runs: type: array items: $ref: '#/components/schemas/RunSummary' pagination: $ref: '#/components/schemas/Pagination' RunDetailResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/RunDetail' # Shared Schemas WorkflowSummary: type: object properties: id: type: string format: uuid name: type: string description: type: string nullable: true isActive: type: boolean totalRuns: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time WorkflowDetail: allOf: - $ref: '#/components/schemas/WorkflowSummary' - type: object properties: aiModel: type: string aiProvider: type: string enum: - ANTHROPIC - OPENAI - GOOGLE steps: type: array items: $ref: '#/components/schemas/WorkflowStep' config: type: object additionalProperties: true RunSummary: type: object properties: id: type: string format: uuid status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED input: type: object nullable: true output: type: object nullable: true error: type: string nullable: true tokensUsed: type: integer nullable: true durationMs: type: integer nullable: true createdAt: type: string format: date-time RunDetail: allOf: - $ref: '#/components/schemas/RunSummary' - type: object properties: workflowId: type: string format: uuid workflowName: type: string Pagination: type: object properties: total: type: integer description: Total number of items limit: type: integer description: Items per page offset: type: integer description: Current offset hasMore: type: boolean description: Whether more items are available # Error Schemas ApiError: type: object required: - success - error properties: success: type: boolean example: false error: type: object required: - code - message properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: object description: Additional error details additionalProperties: true hint: type: string description: Suggestion for resolving the error requestId: type: string format: uuid description: Request ID for support reference

ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: validation_error message: Request validation failed. details: errors: - path: name message: Name is required hint: Check the errors array for specific field issues. WorkflowNotFound: description: Workflow not found content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: workflow_not_found message: Workflow not found. details: workflowId: 123e4567-e89b-12d3-a456-426614174000 hint: Verify the workflow ID is correct and belongs to your account. WorkflowInactive: description: Workflow is inactive content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: workflow_inactive message: This workflow is currently inactive. details: workflowId: 123e4567-e89b-12d3-a456-426614174000 hint: Activate the workflow in the dashboard before executing. RunNotFound: description: Run not found content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: run_not_found message: Run not found. details: runId: 123e4567-e89b-12d3-a456-426614174000 hint: Verify the run ID is correct and belongs to your account. RateLimitExceeded: description: Rate limit exceeded headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: schema: type: integer example: 0 X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: description: Seconds until the rate limit resets schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: rate_limit_exceeded message: Rate limit exceeded. Please try again later. details: limit: 1000 resetAt: 1704067200 hint: Wait for the rate limit window to reset or upgrade your plan. ExecutionError: description: Workflow execution failed content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: ai_error: summary: AI Provider Error value: success: false error: code: ai_provider_error message: The AI provider returned an error. Please try again. details: runId: 123e4567-e89b-12d3-a456-426614174000 hint: This may be a temporary issue with the AI provider. Try again in a few moments. internal_error: summary: Internal Error value: success: false error: code: internal_error message: An error occurred while executing the workflow. details: runId: 123e4567-e89b-12d3-a456-426614174000 hint: If this persists, please contact support. InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: internal_error message: An unexpected error occurred. hint: If this persists, please contact support.

OpenAPI Spec

OpenAPI Spec