# Workflow API endpoints

> Publish a template's selected inputs and outputs as an async endpoint, choose its authentication path, and build on earlier results.

Source: https://kaitoi.io/docs/core/workflow-endpoints/
Section: Kaitoi Core / REST API
Written for: Developers turning a reusable Studio workflow into an application backend.
Prerequisites: A Studio or Enterprise account with workflow API endpoints enabled; A saved user template with an active API endpoint
Last reviewed: 2026-10-24

---

An endpoint exposes chosen fields from a workflow template. It has a stable ID,
an asynchronous execution contract, and a credential separate from a visitor's
Station login.

## Map a public field to a graph input


A published workflow endpoint maps public fields to selected node inputs and identifies its outputs. Its generated endpoint credential is distinct from a general REST key. Inspect the endpoint's current request contract before calling it, retain the execution receipt, and check the returned status and output. Changing a graph does not justify guessing its external field mapping.

Illustrative prompt and poster fields map to selected internal pins, while a private setting stays unexposed. External endpoint naming such as from_task_id and owner REST naming such as fromTaskId belong to different request contracts. The request excerpt asks for a plant portrait through inputs.prompt and outputs:[poster]; the full request and returned file shape still come from the endpoint contract.

*Figure: Expose the intended interface while retaining the endpoint contract.*

## Create and inspect the endpoint

Save the graph as a template, open its details, and choose **Create API
Endpoint**. Select the input and output pins callers should use and review each
field's **API name**. Copy the generated key when it is shown; creation and
regeneration are the points where the full key is returned.

Use endpoint metadata to learn the contract. Return keys use the API names, so
applications should not infer them from the human-facing labels.

## Choose an authentication path

| Path                                    | Authentication and use                                                        |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| External `/v1/run/{endpoint_id}` routes | The endpoint's bearer key; submit, inspect metadata, and poll its tasks       |
| Public `/api/v1/templates/...` routes   | The owner's scoped REST key; discover and run their active template endpoints |

For owner-authenticated discovery, use the templates list with `hasEndpoint=true`
and retrieve the endpoint docs. Read the returned paths rather than guessing
them. `templates:read` and `templates:run` grant different capabilities.

Both paths can spend the endpoint owner's credits. An endpoint key is a
spending credential: keep it on your backend and enforce your application's own
authorization and limits. A Station has a different visitor-paid model.

## Request only the outputs you need

The public run body can name output API names in `outputs`. Omit it to request
all outputs. To build on an earlier successful run, use `fromTaskId` where its
results remain reusable under the documented owner, age, template, and
external-user rules.

For example, a public API body might include:

```json
{
	"inputs": { "prompt": "A fictional neighborhood bookshop" },
	"outputs": ["poster"],
	"fromTaskId": "previous_successful_task_id"
}
```

Those field names are illustrative; use the names from your endpoint docs. The
external route uses its own documented naming, including `from_task_id`, and
multipart upload rules. Do not mix the two request shapes.

## Observe and manage

Store the task ID, poll or stream through the documented route, and fetch
outputs only after the status permits it. Supported public submissions use
`Idempotency-Key` for retry protection. Revoke an endpoint to stop its use, or
regenerate its key when the old credential should stop working.

## Use the endpoint-specific lifecycle

**Discover:** read exposed field names and generated endpoint docs with
templates:read. **Run:** owner REST endpoint calls and their status/events use
templates:run; progress is 0–100. **Reuse:** fromTaskId requires the documented
same-owner/endpoint/revision, retained-success, age and external-user conditions.
The endpoint key is a spending credential, not a visitor Station login.

## Checks and next steps

For an owner REST key, submit through
`POST /templates/{template_id}/endpoints/{endpoint_id}/runs` and observe the
returned task through that same endpoint's run detail or event stream. These
owner execution and observation routes require `templates:run`, not the
public graph run's `runs:read`. Their progress scale is 0–100.

`fromTaskId` reuse is bounded: the prior task must be successful, retained,
for the same owner/endpoint/current template revision, and within the
supported 24-hour window. Any guarded external user must match. It is not a
universal resume of a provider's internal operation.

Read generated endpoint docs for exact `fieldName`s, file values, and current
external/owner routes. The external endpoint-key API uses its own request
shapes; do not transplant the owner REST body's camelCase fields into every
form or multipart request. Endpoint discovery is not authority to spend the
owner's credits.