Run Prompt

curl https://gateway.gatelit.dev/v1/prompts/my-translator/run \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey glk_..." \
  -d '{
    "variables": {
      "source_language": "English",
      "target_language": "French",
      "text": "Hello, how are you?"
    }
  }'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "Explain quantum entanglement in one sentence."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Missing required variable: user_name"
}

{
  "error": true,
  "code": "unauthorized",
  "message": "<string>"
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Prompt not found or has no published version"
}

POST

prompts

{slug}

run

curl https://gateway.gatelit.dev/v1/prompts/my-translator/run \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey glk_..." \
  -d '{
    "variables": {
      "source_language": "English",
      "target_language": "French",
      "text": "Hello, how are you?"
    }
  }'

{
  "id": "<string>",
  "object": "chat.completion",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "Explain quantum entanglement in one sentence."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Missing required variable: user_name"
}

{
  "error": true,
  "code": "unauthorized",
  "message": "<string>"
}

{
  "error": true,
  "code": "gateway_error",
  "message": "Prompt not found or has no published version"
}

POST /v1/prompts/{slug}/run Execute a saved prompt from the dashboard by its slug. The gateway fetches the prompt’s template, interpolates your variables, and routes through the normal chat completions pipeline. By default the published version is used. Use the version query parameter to target a specific version.

Auth

All three schemes are accepted:

Authorization: GatelitKey glk_...
Authorization: GatelitSigned <signed-token>

Bearer (OIDC) is supported but in Alpha. Contact us if you need OIDC auth.

Path parameters

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

Query parameters

Parameter	Type	Default	Description
`version`	`string`	`"published"`	Which version of the prompt to execute

Version values:

Value	Behavior
`published`	Use the currently published version (default)
`current`	Use the latest saved version, even if unpublished — useful for testing drafts
`3` (or any integer)	Use a specific version number (e.g. `?version=2`)

# Run the latest draft (unpublished) version
curl .../v1/prompts/my-translator/run?version=current ...

# Run a specific historical version
curl .../v1/prompts/my-translator/run?version=2 ...

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
`metadata`	`object`	No	Arbitrary string/number/boolean tags — stored on the log entry, stripped before forwarding (same rules as chat completions)
`user`	`string`	No	End-user ID — forwarded to the provider and used as the logged end-user ID

Examples

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

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

File inputs

File variables (type: "file" in the prompt editor) hold either an http(s) URL or a base64 data URL. They are used inside JSON content blocks in the message templates — the same shapes /v1/chat/completions accepts:

[
  { "type": "text", "text": "Extract the data from this document." },
  { "type": "file", "file": { "mime_type": "application/pdf", "file_data": "{{pdf}}" } }
]

curl https://gateway.gatelit.dev/v1/prompts/doc-extractor/run \
  -H "Content-Type: application/json" \
  -H "Authorization: GatelitKey glk_..." \
  -d '{
    "variables": {
      "pdf": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  }'

Supported block shapes:

Block	Payload	Notes
`{"type":"image_url","image_url":{"url":…}}`	`https://…` or `data:image/…;base64,…`	Images on any vision model; URLs are fetched by OpenAI-family providers, and server-side by the gateway for Anthropic and Google
`{"type":"file","file":{"mime_type":"application/pdf","file_data":…}}`	`data:…;base64,…`	PDFs and documents
`{"type":"file","file":{"mime_type":…,"url":…}}`	`https://…`	Always fetched server-side by the gateway into base64 — no provider accepts URL file parts
`{"type":"file","file":{"file_id":…}}`	provider file ID	Anthropic Files API only

file.url is always fetched server-side into base64 (no provider accepts URL file parts). image_url URLs are fetched by the gateway for Anthropic and Google, which only accept base64, and left for OpenAI-family providers to fetch themselves. Text files (text/*, CSV, JSON) are inlined as plain text and work on every model (oversized text files are truncated). Requests whose content blocks the chosen model cannot process are rejected with a 400 — check the model catalog for image/document support.

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, no published version, or specified version does not exist

Authorizations

Authorization

string

header

required

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.

Path Parameters

slug

string

required

The prompt slug from the dashboard.

Pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$

Query Parameters

version

string

default:published

Which version of the prompt to execute.

published — published version (default)
current — latest saved version, even if unpublished
<number> — a specific version number (e.g. 3)

Examples:

"published"

"current"

"3"

Body

application/json

Variables to inject into the saved prompt's template. Which variables are required depends on the prompt's definition in the dashboard.

variables

object

Key-value map of variable name → value.

Show child attributes

metadata

object

Arbitrary tags attached to the request — see the chat completions metadata field. Stored on the log entry, stripped before forwarding.

Show child attributes

user

string

End-user identifier — see the chat completions user field.

stream

boolean

default:false

max_tokens

integer

temperature

number

Required range: 0 <= x <= 2

Response

Same response shape as /v1/chat/completions. Headers include x-gatelit-request-id and x-gatelit-model.

OpenAI-compatible chat completion response. Returned when stream is false (default).

string

object

string

Example:

"chat.completion"

created

integer

model

string

The upstream model that handled the request.

choices

object[]

Show child attributes

usage

object

Show child attributes

How it works

API Reference

Auth

Path parameters

Query parameters

Request body

Examples

File inputs

Response

Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

​Auth

​Path parameters

​Query parameters

​Request body

​Examples

​File inputs

​Response

​Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

Auth

Path parameters

Query parameters

Request body

Examples

File inputs

Response

Errors