Get active prompt
Returns whichever prompt version is live on an engine, with your values filled in.
https://api.promptengine.co.in/v1/engines/{engine_id}/active-promptParameters
| Field | In | Type | Description |
|---|---|---|---|
| engine_id | path | integer | Which engine to read. Shown on the engine's page. |
| variables | body | object | Values to substitute into the prompt's {{placeholders}}. Send {} or omit the body entirely for none.Optional. |
The response
Every field is always present, and always the same type. None of them are conditional on the kind of prompt that happens to be live:
{
"success": true,
"data": {
"version": "2.1",
"mode": "text",
"messages": [
{ "role": "system", "content": "You are a support analyst for Acme Cloud." },
{ "role": "user", "content": "Summarize this ticket in 3 bullets." }
],
"text": "You are a support analyst for Acme Cloud.\n\nSummarize this ticket in 3 bullets.",
"missing_variables": [{ "name": "ticket_body" }]
},
"error": null
}Everything above sits under data:
| Field | Type | Description |
|---|---|---|
| messages | array | The prompt in chat form — the shape every chat API takes. Always exactly two entries, system then user, whatever kind of prompt is live. This is the field you want. |
| text | string | The same content flattened to one string, for completion-style APIs. Always present. |
| version | string | Which version answered, e.g. "2.1". Worth logging — it is how you correlate a change in output with a change in prompt. |
| mode | string | null | "text" or "image" for Kitchen prompts. null for plain templates, which carry no provider, so the intended kind of model is unknown to us. |
| missing_variables | array | Variables you sent no value for, as { name } objects. Their placeholders were left empty rather than rejected, so a typo'd key surfaces here instead of failing silently. |
One shape, every prompt
The two examples below come from different engines running different kinds of prompt — a plain template and a Kitchen-built one with its own system message. Same fields, same types, in the same places.
That is the whole point. Rebuild a prompt, fork a version, switch it from a plain template to a Kitchen one, activate it — this code keeps working and never learns anything changed:
const { data } = await getActivePrompt(12, {
customer_name: "Ada",
});
await openai.chat.completions.create({
model: "gpt-4o",
messages: data.messages,
});messages is always exactly two entries — a system then a user — in that order. A prompt with no system content reports it as an empty string rather than dropping the entry, so messages[1] is the user message today and after any change you make in the dashboard.
If your provider dislikes a blank system message, drop it in one line: messages.filter((m) => m.content).
How variables behave
Anywhere the prompt contains {{customer_name}}, we substitute the value you sent under that exact key.
A placeholder you send no value for is left empty, not rejected — the call still returns 200. Every name that came back empty is listed in missing_variables as a { name } object, so a typo shows up there rather than silently producing a subtly wrong prompt. Keys you send that the prompt never mentions are ignored.
A missing value degrades one call rather than taking your feature down. If you would rather fail loudly, check missing_variables and throw. To know the expected names ahead of time, call List variables.
Values do not have to be strings. Numbers, arrays and objects are accepted and serialized before substitution — an array arrives in the prompt as JSON.
Examples
Real responses, captured from the API — not written by hand.
Plain template
A prompt written directly in the editor. It has no system content, so that entry comes back empty — but it comes back.
{
"success": true,
"data": {
"version": "1.0",
"mode": null,
"messages": [
{ "role": "system", "content": "" },
{
"role": "user",
"content": "You are a support agent for Acme.\n\nReply to Ada about their recent order.\nKeep the tone friendly and under 120 words."
}
],
"text": "You are a support agent for Acme.\n\nReply to Ada about their recent order.\nKeep the tone friendly and under 120 words.",
"missing_variables": []
},
"error": null
}Kitchen prompt
A completely different kind of prompt, with a real system message — and exactly the same fields, in the same places, in the same order.
{
"success": true,
"data": {
"version": "1.0",
"mode": "text",
"messages": [
{
"role": "system",
"content": "You are a support analyst for Acme Cloud.\n\nBe factual and concise.\nNever invent details that are not in the ticket."
},
{
"role": "user",
"content": "Summarize the following support ticket in 3 bullets:\n\nCannot log in since Tuesday."
}
],
"text": "You are a support analyst for Acme Cloud.\n\nBe factual and concise.\nNever invent details that are not in the ticket.\n\nSummarize the following support ticket in 3 bullets:\n\nCannot log in since Tuesday.",
"missing_variables": []
},
"error": null
}Missing values
Only customer_name was sent. The other placeholders resolve to nothing and are named back to you — the call still succeeds.
{
"success": true,
"data": {
"version": "1.0",
"mode": null,
"messages": [
{ "role": "system", "content": "" },
{
"role": "user",
"content": "You are a support agent for .\n\nReply to Ada about their recent order.\nKeep the tone and under 120 words."
}
],
"text": "You are a support agent for .\n\nReply to Ada about their recent order.\nKeep the tone and under 120 words.",
"missing_variables": [{ "name": "company" }, { "name": "tone" }]
},
"error": null
}Errors
What this endpoint can return. The envelope is the same everywhere — see Errors for the shape and how to handle it.
Try it
Calls the real endpoint, exactly as your backend would. Paste an API key to run it.
The same call, in code
Updates as you edit the form below. Set PROMPT_ENGINE_KEY in your environment — don't paste the key into your source.
curl -X POST \
https://api.promptengine.co.in/v1/engines/{engine_id}/active-prompt \
-H "Authorization: Bearer $PROMPT_ENGINE_KEY" \
-H "Content-Type: application/json" \
-d '{"variables":{}}'