Skip to main content

API Documentation

The STELLWERK API provides programmatic access to execute flows and retrieve results. All endpoints return JSON and require authentication via API key.

Authentication

Required

There are two authentication contexts. Production access for external clients always uses an API key.

Recommended

API Key (Machine-to-Machine)

Provide an API key via the Authorization header (preferred) or X-API-Key header. The key determines the tenant context. 

Authorization: Bearer your_api_key_here
# or alternatively
X-API-Key: your_api_key_here
Internal Only

Session + CSRF

When the signed-in web dashboard calls the API (same-origin), Rails session + CSRF token are used. Do not build external integrations using this path.

Legacy X-Tenant-ID header-based unauthenticated access has been removed. Always send an API key outside the dashboard.

Request Headers

Header Required Description
Authorization Yes* Bearer token for API key authentication
X-API-Key Alt Alternative to Authorization header
Content-Type Yes Must be application/json
X-CSRF-Token Session Required only for session-based requests from web app

* Either Authorization or X-API-Key is required for API access.

List Flows

GET
GET /api/v1/flows

Returns a list of all active flows for the authenticated tenant, ordered by most recently updated.

Response

// 200 OK
{
  "flows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Pricing Calculator",
      "slug": "pricing-calculator",
      "description": "Calculate dynamic pricing based on parameters",
      "status": "active",
      "created_at": "2025-07-08T10:00:00Z",
      "updated_at": "2025-07-08T14:30:00Z"
    }
  ]
}

Response Fields

  • id UUID identifier for the flow
  • slug URL-friendly identifier (can be used in place of ID)
  • status Always "active" for this endpoint (draft/archived flows are excluded)

Get Flow Details

GET
GET /api/v1/flows/:id_or_slug

Retrieve details for a specific flow. You can reference the flow by either its UUID or its slug.

Response

// 200 OK
{
  "flow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Pricing Calculator",
    "slug": "pricing-calculator",
    "description": "Calculate dynamic pricing based on parameters",
    "status": "active",
    "metadata": {
      "version": "1.2",
      "category": "pricing"
    },
    "nodes_count": 5,
    "created_at": "2025-07-08T10:00:00Z",
    "updated_at": "2025-07-08T14:30:00Z"
  }
}

Additional Fields

  • metadata Custom key-value data attached to the flow (JSONB)
  • nodes_count Number of nodes in the flow graph

Execute Flow

POST
POST /api/v1/flows/:id_or_slug/execute

Execute a flow with the provided input parameters. The flow engine evaluates all nodes and returns the computed outputs.

Request Body

{
  "inputs": {
    "quantity": 10,
    "unit_price": 25.50,
    "customer_tier": "gold"
  }
}

Note: The API also accepts params as an alternative key to inputs.

200 OK

Success Response

{
  "flow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Pricing Calculator",
    "slug": "pricing-calculator"
  },
  "inputs": {
    "quantity": 10,
    "unit_price": 25.50,
    "customer_tier": "gold"
  },
  "result": {
    "type": "flow_evaluation",
    "flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_name": "Pricing Calculator",
    "flow_slug": "pricing-calculator",
    "execution_status": "success",
    "outputs": {
      "subtotal": 255.00,
      "discount": 25.50,
      "total": 229.50
    },
    "context": {
      "quantity": 10,
      "unit_price": 25.50,
      "customer_tier": "gold",
      "discount_rate": 0.1
    },
    "applied_nodes": ["start_1", "calc_price", "calc_discount", "end_1"],
    "errors": []
  },
  "requirements": {
    "declared_types": {
      "quantity": "integer",
      "unit_price": "number",
      "customer_tier": "string"
    },
    "required_without_defaults": ["quantity", "unit_price"]
  },
  "executed_at": "2025-07-08T14:35:22Z"
}

Response Fields

result object

  • outputs Final computed values from EndNode(s)
  • context All variables in scope after execution (inputs + computed)
  • applied_nodes List of node IDs that were executed (in order)
  • execution_status "success" or "failed"

requirements object

  • declared_types Type declarations from the StartNode input schema
  • required_without_defaults Input names that are required and have no default value
422

Execution Error

{
  "success": false,
  "error": "Flow execution failed",
  "details": {
    "flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_name": "Pricing Calculator",
    "execution_status": "failed",
    "errors": [
      "Required input missing: quantity",
      "Invalid type for unit_price: expected number"
    ]
  }
}
402

Quota Exceeded

{
  "success": false,
  "error": "execution_quota_exceeded",
  "details": {
    "message": "Monthly execution quota reached for your plan.",
    "plan": "starter",
    "limit": 10000
  }
}

Test Cases

Flows can have associated test cases for validation. These endpoints allow you to manage and run test cases programmatically.

GET

List Test Cases

GET /api/v1/flows/:flow_id/test_cases
GET

Get Test Case

GET /api/v1/flows/:flow_id/test_cases/:id
POST

Create Test Case

POST /api/v1/flows/:flow_id/test_cases
PATCH

Update Test Case

PATCH /api/v1/flows/:flow_id/test_cases/:id
DELETE

Delete Test Case

DELETE /api/v1/flows/:flow_id/test_cases/:id
POST

Run Test Case

POST /api/v1/flows/:flow_id/test_cases/:id/run

Executes the flow with the test case's predefined inputs and compares the result against expected outputs.

Error Responses

400

Bad Request

{
  "error": "Missing parameter: inputs"
}
401

Unauthorized

{
  "error": "Authentication required"
}
402

Payment Required

{
  "success": false,
  "error": "execution_quota_exceeded",
  "details": { "message": "Monthly execution quota reached for your plan." }
}
404

Not Found

{
  "error": "Record not found"
}
422

Unprocessable Entity

{
  "success": false,
  "error": "Flow execution failed",
  "details": {
    "errors": ["Required input missing: quantity"]
  }
}

cURL Examples

Base URLs

  • Production: https://api.stellwerk.io
  • Development: http://localhost:3000

List Flows

curl \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  https://api.stellwerk.io/api/v1/flows

Get Flow Details

curl \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  https://api.stellwerk.io/api/v1/flows/pricing-calculator

Execute Flow

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"quantity":10,"unit_price":25.50}}' \
  https://api.stellwerk.io/api/v1/flows/pricing-calculator/execute

Using X-API-Key Header

curl \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  https://api.stellwerk.io/api/v1/flows