Skip to main content
The schema endpoints return the input field definitions from a workflow’s Request Input node. Use them to discover exactly which field names, types, and default values the workflow expects before scripting calls to POST /api/workflows/:slug/run.
Always call the schema endpoint before writing automation scripts against a workflow you didn’t build. The field names returned here are the exact keys you pass in the inputs object when running the workflow. Skipping this step is the most common cause of INVALID_INPUTS errors.

​
Authenticated schema

GET /api/workflows/:slug/schema
Returns the full input field map for the workflow. This endpoint requires authentication. Auth: capability workflow:read. Path parameter:
​
slug
string
required
The workflow’s URL slug.
Example: 
curl https://knouds.ai/api/workflows/my-thumbnail-pipeline/schema \
  -H "x-api-key: $KNOUDS_KEY"

​
Public schema (no auth)

GET /api/workflows/:slug/public-schema
Returns the same field map without requiring authentication. This endpoint is only available when the workflow has publicPlayground: true set. If the workflow is not marked as a public playground, this endpoint returns 404. Use this endpoint when you are building an unauthenticated form or an embed that collects user inputs before passing them to a server-side call. Auth: none required. Path parameter:
​
slug
string
required
The workflow’s URL slug.
Example: 
curl https://knouds.ai/api/workflows/my-thumbnail-pipeline/public-schema

​
Response

Both endpoints return the same shape:
​
fields
array
An array of input field definitions. Each field describes one key in the inputs object you pass to POST /api/workflows/:slug/run.
​
values
object
The current saved values for each field, as last set in the editor.
​
name
string
The workflow’s display name.
​
description
string
The workflow’s description.
​
estimatedCreditCost
number
Estimated credits this workflow costs to run, calculated from the generator nodes and your account tier. Only present on the authenticated /schema endpoint.
Example response: 
{
  "fields": [
    {
      "name": "prompt",
      "type": "text",
      "label": "Prompt",
      "default": ""
    },
    {
      "name": "aspect_ratio",
      "type": "select",
      "label": "Aspect ratio",
      "options": ["16:9", "1:1", "9:16"],
      "default": "16:9"
    }
  ],
  "values": {
    "prompt": "",
    "aspect_ratio": "16:9"
  },
  "name": "My Thumbnail Pipeline",
  "description": "Generates thumbnails from a prompt and aspect ratio",
  "estimatedCreditCost": 12
}
The actual field shape depends entirely on what the workflow author configured in the Request Input node. Field types, options, and defaults are set per-workflow. If a workflow has no Request Input node, the fields array is empty and the workflow accepts an empty inputs object.

​
Using the schema to build a run request

Once you have the schema, map each field.name to a value in the inputs object: 
# 1. Fetch the schema
curl https://knouds.ai/api/workflows/my-thumbnail-pipeline/schema \
  -H "x-api-key: $KNOUDS_KEY"

# 2. Use the field names to build the run request
curl -X POST https://knouds.ai/api/workflows/my-thumbnail-pipeline/run \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "prompt": "a futuristic city at dawn",
      "aspect_ratio": "16:9"
    }
  }'
Fields you omit from inputs fall back to their default values as defined in the schema.