> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gatelit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/prompts/:id/run

> Execute a published saved prompt by its UUID, with optional variable substitutions and runtime overrides.

## Endpoint

```
POST /v1/prompts/:id/run
```

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

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

The response format is identical to [`POST /v1/chat/completions`](/api/chat-completions).

<Warning>
  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.
</Warning>

***

## 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

<ParamField body="variables" type="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`.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Enable Server-Sent Events streaming. Uses the same SSE format as `/v1/chat/completions`.
</ParamField>

<ParamField body="overrides" type="object">
  Runtime overrides applied on top of the prompt's saved configuration.

  <Expandable title="Override fields">
    <ParamField body="model" type="string">
      Override the prompt's configured model. Must be in `"provider/model-name"` format.
    </ParamField>

    <ParamField body="temperature" type="number">
      Override the prompt's configured temperature.
    </ParamField>

    <ParamField body="max_tokens" type="number">
      Override the prompt's configured max token limit.
    </ParamField>
  </Expandable>
</ParamField>

***

## Response

The response is identical in structure to [`POST /v1/chat/completions`](/api/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

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

  ```bash With variables theme={null}
  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"
      }
    }'
  ```

  ```bash With overrides and streaming theme={null}
  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
      }
    }'
  ```
</CodeGroup>

***

## 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.

<Note>
  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.
</Note>

***

## 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](/api/errors) for the full error shape and handling guidance.