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

# Run Prompt

> Execute a saved prompt by slug with variable interpolation.

`POST /v1/prompts/{slug}/run`

Execute a saved prompt from the dashboard by its slug. The gateway fetches the published version, interpolates your variables into the template, and routes through the normal chat completions pipeline.

## Auth

All three schemes are accepted:

```http theme={null}
Authorization: GatelitKey sk_live_...
Authorization: GatelitSigned <signed-token>
```

<Info>
  `Bearer` (OIDC) is supported but in **Alpha**. Contact us if you need OIDC auth.
</Info>

## Path parameters

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `slug`    | `string` | The prompt slug from the dashboard |

## Request body

| Field         | Type      | Required | Description                               |
| ------------- | --------- | -------- | ----------------------------------------- |
| `variables`   | `object`  | No       | Key-value map of variable name → value    |
| `stream`      | `boolean` | No       | Enable SSE streaming (default: `false`)   |
| `max_tokens`  | `integer` | No       | Override the prompt's default max tokens  |
| `temperature` | `number`  | No       | Override the prompt's default temperature |

## Examples

```bash theme={null}
curl https://gateway.gatelit.dev/v1/prompts/customer-support/run \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_..." \
  -d '{
    "variables": {
      "tone": "friendly and professional",
      "language": "Spanish",
      "user_message": "My order hasn't arrived."
    }
  }'
```

```bash theme={null}
curl https://gateway.gatelit.dev/v1/prompts/my-assistant/run \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey sk_live_..." \
  -d '{
    "variables": { "user_name": "Alice" },
    "stream": true
  }'
```

## Response

Same shape as `/v1/chat/completions`. Response headers include `x-gatelit-request-id` and `x-gatelit-model`.

## Errors

| Status | Code            | Meaning                                  |
| ------ | --------------- | ---------------------------------------- |
| 400    | `gateway_error` | Missing required variables               |
| 401    | `unauthorized`  | Missing or invalid token                 |
| 404    | `gateway_error` | Prompt not found or no published version |


## OpenAPI

````yaml post /v1/prompts/{slug}/run
openapi: 3.1.0
info:
  title: Gatelit Gateway API
  version: '1.0'
  description: |
    The Gatelit gateway is a single HTTP endpoint that routes AI requests to any
    supported provider. It handles authentication, provider key resolution,
    request transformation, stream normalisation, spend tracking, and logging.

    All requests must include an `Authorization` header. Three auth schemes are
    supported — choose based on your deployment scenario.
servers:
  - url: https://gateway.yourapp.com
    description: Your gateway URL
security: []
paths:
  /v1/prompts/{slug}/run:
    post:
      summary: Run a saved prompt
      description: >
        Execute a saved prompt from the dashboard by its slug. The gateway
        fetches

        the published version (cached for 60s in KV), interpolates your
        variables

        into the template, and routes through the normal chat completions
        pipeline.


        The model, system prompt, and default parameters are all configured

        in the dashboard — you only pass variables.


        You can also pass `temperature` and `max_tokens` to override the

        prompt's defaults at runtime.
      operationId: runPrompt
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
          description: The prompt slug from the dashboard.
          example: my-translator
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptRunRequest'
            examples:
              variables:
                summary: With variables
                value:
                  variables:
                    user_name: Alice
                    product: Gatelit
              streaming:
                summary: Streaming
                value:
                  variables:
                    topic: Quantum computing
                  stream: true
      responses:
        '200':
          description: >-
            Same response shape as `/v1/chat/completions`. Headers include
            `x-gatelit-request-id` and `x-gatelit-model`.
          headers:
            x-gatelit-request-id:
              schema:
                type: string
            x-gatelit-model:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          description: Missing required variables or invalid configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatelitError'
              example:
                error: true
                code: gateway_error
                message: 'Missing required variable: user_name'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatelitError'
        '404':
          description: Prompt not found or has no published version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatelitError'
              example:
                error: true
                code: gateway_error
                message: Prompt not found or has no published version
      security:
        - BearerToken: []
        - GatelitSigned: []
        - GatelitKey: []
      x-codeSamples:
        - lang: curl
          label: curl — run a prompt
          source: |
            curl https://gateway.yourapp.com/v1/prompts/my-translator/run \
              -H "Content-Type: application/json" \
              -H "Authorization: GatelitKey sk_live_..." \
              -d '{
                "variables": {
                  "source_language": "English",
                  "target_language": "French",
                  "text": "Hello, how are you?"
                }
              }'
        - lang: curl
          label: curl — streaming prompt
          source: |
            curl https://gateway.yourapp.com/v1/prompts/my-assistant/run \
              -H "Content-Type: application/json" \
              -H "Authorization: GatelitKey sk_live_..." \
              -d '{
                "variables": { "user_name": "Alice" },
                "stream": true
              }'
        - lang: ts
          label: SDK — tag request with prompt ID
          source: |
            import { GatelitClient } from "@gatelit/sdk"

            const client = new GatelitClient({
              gatewayUrl: "https://gateway.yourapp.com",
              getToken: async () => ({
                token: "sk_live_...",
                scheme: "GatelitKey",
              }),
            })

            const response = await client.chat({
              model: "openai/gpt-4o",
              messages: [{ role: "user", content: "placeholder" }],
              promptId: "my-translator",
            })
components:
  schemas:
    PromptRunRequest:
      type: object
      description: >
        Variables to inject into the saved prompt's template.

        Which variables are required depends on the prompt's definition in the
        dashboard.
      properties:
        variables:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          description: Key-value map of variable name → value.
        stream:
          type: boolean
          default: false
        max_tokens:
          type: integer
        temperature:
          type: number
          minimum: 0
          maximum: 2
    ChatCompletionsResponse:
      type: object
      description: |
        OpenAI-compatible chat completion response.
        Returned when `stream` is false (default).
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
          description: The upstream model that handled the request.
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                enum:
                  - stop
                  - length
                  - tool_calls
                  - content_filter
        usage:
          $ref: '#/components/schemas/Usage'
    GatelitError:
      type: object
      required:
        - error
        - code
        - message
      properties:
        error:
          type: boolean
          enum:
            - true
        code:
          type: string
          enum:
            - unauthorized
            - gateway_error
            - provider_error
            - forbidden
            - policy_violation
            - rate_limit_exceeded
            - model_not_allowed
            - token_limit_exceeded
        message:
          type: string
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
        content:
          type: string
      example:
        role: user
        content: Explain quantum entanglement in one sentence.
      x-codeSample: |
        // SDK
        const msg: ChatMessage = {
          role: "user",
          content: "Explain quantum entanglement in one sentence."
        }
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Tokens consumed by the input (system prompt + messages).
        completion_tokens:
          type: integer
          description: Tokens generated in the response.
        total_tokens:
          type: integer
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      description: >
        OIDC JWT issued by your auth provider (Alpha).

        Full self-serve configuration is coming soon — contact us for early
        access.

        Use this for browser/frontend clients where a user is signed in.
    GatelitSigned:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Short-lived HMAC-signed token issued by your backend.
        Format: `GatelitSigned <token>`

        Generate with `signToken()` from `@gatelit/sdk`:
        ```ts
        import { signToken } from "@gatelit/sdk/sign"
        const token = await signToken(
          { sub: "user-123", orgId: "org-abc", ttl: 60 },
          process.env.GATELIT_SIGNING_SECRET!
        )
        ```
    GatelitKey:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Long-lived service key for backend-to-backend use.
        Format: `GatelitKey sk_live_...`

        Create service keys in the dashboard under Settings → Service Keys.

````