Workflows API

The Workflows API allows you to programmatically trigger and manage workflow runs. You can list available workflows, create runs with inputs, monitor execution progress, provide step-level inputs, and cancel runs.

Authentication

All requests require an API key. See Managing API Keys.

Authorization: Bearer YOUR_API_KEY

Base URL

https://app.revelry.ai/api/v1

---

Endpoints

List Workflows

List all workflows for your organization.

Endpoint: GET /api/v1/workflows

curl https://app.revelry.ai/api/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workflows": [
    {
      "id": 1,
      "name": "Generate PRD",
      "organization_id": 10,
      "steps": [
        {
          "name": "Gather Requirements",
          "input_definitions": [
            {
              "name": "product_name",
              "type": "text",
              "description": "Name of the product",
              "required": true,
              "provided": false,
              "value": null
            }
          ]
        }
      ]
    }
  ]
}

---

Get Workflow

Get details for a single workflow, including its steps and input definitions.

Endpoint: GET /api/v1/workflows/:id

curl https://app.revelry.ai/api/v1/workflows/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workflow": {
    "id": 1,
    "name": "Generate PRD",
    "organization_id": 10,
    "steps": [
      {
        "name": "Gather Requirements",
        "input_definitions": [
          {
            "name": "product_name",
            "type": "text",
            "description": "Name of the product",
            "required": true,
            "provided": false,
            "value": null
          }
        ]
      }
    ]
  }
}

---

List Workflow Runs

List all runs for a given workflow, with optional filtering and pagination.

Endpoint: GET /api/v1/workflows/:workflow_id/runs

Query Parameters:

Parameter	Type	Required	Description
project_id	integer	No	Filter runs by project
limit	integer	No	Number of results to return
offset	integer	No	Number of results to skip

curl "https://app.revelry.ai/api/v1/workflows/1/runs?project_id=5&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workflow_runs": [
    {
      "id": 42,
      "name": "Run 2025-01-15 14:30",
      "execution_status": "completed",
      "workflow_id": 1,
      "project_id": 5,
      "created_by_id": 7,
      "workflow_run_steps": [
        {
          "id": 100,
          "name": "Gather Requirements",
          "type": "artifact_generation",
          "execution_status": "completed",
          "workflow_run_id": 42,
          "artifact_id": 789,
          "artifact": { "id": 789, "title": "PRD - My Product" },
          "user_input_values": { "product_name": "My Product" },
          "input_definitions": []
        }
      ]
    }
  ]
}

---

Create Workflow Run

Start a new workflow run. You can optionally provide user inputs for steps upfront.

Endpoint: POST /api/v1/workflows/:workflow_id/runs

Request Body:

Field	Type	Required	Description
project_id	integer	Yes	Project to run the workflow in
user_inputs	object	No	Map of step name to input values

curl -X POST https://app.revelry.ai/api/v1/workflows/1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 5,
    "user_inputs": {
      "Gather Requirements": {
        "product_name": "My Product",
        "feature_description": "User authentication system"
      }
    }
  }'

Response:

{
  "workflow_run": {
    "id": 43,
    "name": null,
    "execution_status": "pending",
    "workflow_id": 1,
    "project_id": 5,
    "created_by_id": null,
    "workflow_run_steps": [
      {
        "id": 101,
        "name": "Gather Requirements",
        "type": "artifact_generation",
        "execution_status": "pending",
        "workflow_run_id": 43,
        "artifact_id": null,
        "artifact": null,
        "user_input_values": {
          "product_name": "My Product",
          "feature_description": "User authentication system"
        },
        "input_definitions": [
          {
            "name": "product_name",
            "type": "text",
            "description": "Name of the product",
            "required": true,
            "provided": true,
            "value": "My Product"
          }
        ]
      }
    ]
  }
}

---

Get Workflow Run

Get details of a specific run, including all steps and their statuses.

Endpoint: GET /api/v1/workflows/:workflow_id/runs/:run_id

curl https://app.revelry.ai/api/v1/workflows/1/runs/43 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: Same structure as the create run response, with updated execution_status values.

---

Cancel Workflow Run

Cancel a run that is currently in progress.

Endpoint: POST /api/v1/workflows/:workflow_id/runs/:run_id/cancel

curl -X POST https://app.revelry.ai/api/v1/workflows/1/runs/43/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workflow_run": {
    "id": 43,
    "execution_status": "cancelling",
    "..."
  }
}

Note: Returns 400 if the run cannot be cancelled in its current status (e.g., already completed or failed).

---

Get Step Details

Get details of a specific step within a run, including its input definitions and current values.

Endpoint: GET /api/v1/workflows/:workflow_id/runs/:run_id/steps/:step_id

curl https://app.revelry.ai/api/v1/workflows/1/runs/43/steps/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workflow_run_step": {
    "id": 101,
    "name": "Gather Requirements",
    "type": "artifact_generation",
    "execution_status": "awaiting_user_input",
    "workflow_run_id": 43,
    "artifact_id": null,
    "artifact": null,
    "user_input_values": {},
    "input_definitions": [
      {
        "name": "product_name",
        "type": "text",
        "description": "Name of the product",
        "required": true,
        "provided": false,
        "value": null
      }
    ]
  }
}

---

Provide Step Input

Provide user inputs for a step that is awaiting input. This allows you to fill in required values so the step can proceed with execution.

Endpoint: PATCH /api/v1/workflows/:workflow_id/runs/:run_id/steps/:step_id

Request Body:

Field	Type	Required	Description
user_inputs	object	Yes	Map of input name to value

curl -X PATCH https://app.revelry.ai/api/v1/workflows/1/runs/43/steps/101 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_inputs": {
      "product_name": "My Product",
      "feature_description": "User authentication system"
    }
  }'

Response:

{
  "workflow_run_step": {
    "id": 101,
    "name": "Gather Requirements",
    "type": "artifact_generation",
    "execution_status": "awaiting_user_input",
    "workflow_run_id": 43,
    "artifact_id": null,
    "artifact": null,
    "user_input_values": {
      "product_name": "My Product",
      "feature_description": "User authentication system"
    },
    "input_definitions": [
      {
        "name": "product_name",
        "type": "text",
        "description": "Name of the product",
        "required": true,
        "provided": true,
        "value": "My Product"
      }
    ]
  }
}

---

Run Status Lifecycle

Workflow runs progress through the following statuses:

Status	Description
pending	Run created, not yet started
executing	Steps are being processed
completed	All steps finished successfully
failed	One or more steps encountered an error
cancelling	Cancel has been requested
cancelled	Run was successfully cancelled

Step Input Workflow

When a run reaches awaiting_user_input status:

1. Poll the run with GET /workflows/:workflow_id/runs/:run_id to check status
2. Find the step with execution_status: "awaiting_user_input"
3. Review input_definitions to see what inputs are needed (required: true, provided: false)
4. Provide inputs with PATCH /workflows/:workflow_id/runs/:run_id/steps/:step_id
5. The run continues automatically once all required inputs are provided

---

Error Responses

Status Code	Description
400	Invalid request (e.g., cannot cancel a completed run)
401	Invalid or missing API key
404	Workflow, run, or step not found
429	Rate limit exceeded

{
  "error": {
    "message": "Workflow run cannot be cancelled in its current status."
  }
}

---

Next Steps

• API Usage Guide - Artifact generation via API
• Management API - CRUD operations for platform resources
• Managing API Keys - Set up authentication
• Workflows Overview - Understanding workflows