POST /v1/prompts/:id/run

Endpoint

POST /v1/prompts/:id/run

Executes a saved prompt from the Gatelit dashboard by its UUID. The gateway:

Fetches the prompt’s published version (cached for fast retrieval).
Resolves any prompt partials ({{> partial_name}}).
Interpolates {{variable_name}} tokens with the values you supply.
Merges any runtime overrides (model, temperature, max tokens).
Routes the assembled request through the normal /v1/chat/completions pipeline.

The response format is identical to POST /v1/chat/completions.

Only published prompt versions are executed. If a prompt exists but has no published version, the gateway returns a 404. Save and publish your prompt in the dashboard before calling this endpoint.

Authentication

Same Authorization header schemes as /v1/chat/completions:

Header value	When to use
`GatelitSigned <token>`	Backend-issued HMAC signed token
`Bearer <token>`	OIDC token from Clerk, Supabase, or Auth0
`GatelitKey <key>`	Long-lived service key (backend-to-backend)

Path parameter

Parameter	Type	Description
`id`	`string` (UUID)	The UUID of the saved prompt. Copy it from the prompt’s detail page in the dashboard.

Request

Content-Type: application/json

Body fields

object

Key-value pairs for {{variable_name}} substitutions in the prompt’s system prompt and user message templates.Variable names must match [A-Za-z_][A-Za-z0-9_]*. Values are coerced to the type declared in the prompt’s variable definitions:

Declared type	Accepted values
`string`	Any string
`number`	A number or a numeric string
`boolean`	`true`/`false`, or `"true"`/`"false"`, `"1"`/`"0"`, `"yes"`/`"no"`
`json`	A JSON-parseable string, or any object/array value

If a required variable is missing, the gateway returns 400.

boolean

default:"false"

Enable Server-Sent Events streaming. Uses the same SSE format as /v1/chat/completions.

object

Runtime overrides applied on top of the prompt’s saved configuration.

Show Override fields

string

Override the prompt’s configured model. Must be in "provider/model-name" format.

number

Override the prompt’s configured temperature.

number

Override the prompt’s configured max token limit.

Response

The response is identical in structure to POST /v1/chat/completions — an OpenAI-compatible completion object for non-streaming requests, or an SSE stream when stream: true. Response headers include x-gatelit-request-id, x-gatelit-model, and x-gatelit-auth-mode.

Examples

curl https://gateway.yourapp.com/v1/prompts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run \
  -H "Authorization: GatelitSigned <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://gateway.yourapp.com/v1/prompts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run \
  -H "Authorization: GatelitSigned <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "user_name": "Alice",
      "topic": "renewable energy",
      "word_limit": "200"
    }
  }'

curl https://gateway.yourapp.com/v1/prompts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run \
  -H "Authorization: GatelitSigned <token>" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "variables": {
      "article_text": "..."
    },
    "stream": true,
    "overrides": {
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "temperature": 0.3,
      "max_tokens": 512
    }
  }'

Partial resolution

If your prompt templates reference partials with {{> partial_name}}, the gateway resolves them automatically before variable interpolation. This means partials can themselves contain {{variable_name}} tokens — they are expanded in the correct order.

Partials not found in the dashboard are substituted with an empty string rather than causing an error, so your prompt degrades gracefully if a partial is deleted.

Error codes

HTTP status	Code	Cause
`404`	`gateway_error`	Prompt not found, or the prompt has no published version.
`400`	`gateway_error`	A required variable was not supplied in the `variables` object.
`401`	`unauthorized`	Missing or invalid auth token.

See the Errors reference for the full error shape and handling guidance.

JavaScript SDK

Vue SDK

Gateway API

POST /v1/prompts/:id/run

Endpoint

Authentication

Path parameter

Request

Body fields

Response

Examples

Partial resolution

Error codes

​Endpoint

​Authentication

​Path parameter

​Request

​Body fields

​Response

​Examples

​Partial resolution

​Error codes

Endpoint

Authentication

Path parameter

Request

Body fields

Response

Examples

Partial resolution

Error codes