---
title: "Run template endpoint"
method: POST
path: "/api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs"
tags: ["Templates"]
---

# Run template endpoint

`POST /api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/templates/{template_id}/endpoints/{endpoint_id}/runs`
- Auth: HTTP bearer

Submits an owner-authenticated run for an active endpoint on a user-owned template. The API key user must own the template and endpoint, the key must have `templates:run`, file inputs must reference Public API fileIds, and execution may spend the owner's credits. Use `Idempotency-Key` so network retries do not submit duplicate jobs.

## Path parameters

- `template_id` string, required
- `endpoint_id` string, required

## Headers

- `Idempotency-Key` string, nullable
- `authorization` string, nullable

## Request body

- PublicTemplateRunCreateRequest
  - `inputs` object: Input values keyed by exposed endpoint fieldName. File inputs should use {"type":"file","fileId":"..."}; primitive values may use typed wrappers or direct JSON values.
  - `externalId` string, nullable
  - `externalUserId` string, nullable: Developer end-user guard. Referenced files with externalUserId must match this value.
  - `externalWorkspaceId` string, nullable

## Response `202`

Accepted template endpoint run.

- PublicTemplateRunDetail
  - `taskId` string, required: Workflow task id used to poll this template endpoint run.
  - `sourceType` 'template_endpoint'
  - `templateId` string, required
  - `endpointId` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `progress` integer, nullable
  - `progressMessage` string, nullable
  - `nodesCount` integer, nullable
  - `nodeIndex` integer, nullable
  - `currentNode` string, nullable
  - `logs` object[]
  - `externalId` string, nullable
  - `externalUserId` string, nullable
  - `externalWorkspaceId` string, nullable
  - `inputFiles` PublicRunFileInputReference[]
    - `nodeId` string, required
    - `inputName` string, required
    - `fileId` string, required
    - `filename` string, required
    - `contentType` string, required
    - `sizeBytes` integer, required
    - `externalId` string, nullable
    - `externalUserId` string, nullable
    - `externalWorkspaceId` string, nullable
  - `outputs` object
  - `error` object, nullable
  - `executionTimeMs` integer, nullable
  - `createdAt` string, date-time, nullable
  - `updatedAt` string, date-time, nullable

## Other responses

- `400`: The run inputs or file references are invalid.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `404`: The template, endpoint, or input file was not found.
- `409`: The Idempotency-Key conflicts with a different request.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `503`: The shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)