Use stored prompts

A stored prompt holds the instructions a model reads before the conversation: who it is, what it may do, how to answer. You write it once in the console, your code sends only its name, and you can change it later without deploying anything.

Create a prompt

In the console, open the project, then AI, then Prompts, and select New prompt. Give it:

• A name, such as support-agent. Your code uses it, so it cannot change later.
• Instructions. Put {{name}} where each call fills in a value, such as {{customer}}. The console lists the variables it finds as you type.

Only people with Developer access or more can create, change, or delete prompts. API keys can use and read them, never change them.

Use it in a call

Send the prompt’s name in prompt.id, and a value for every variable:

curl -s "$AI_URL/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "prompt": {
      "id": "support-agent",
      "variables": { "customer": "Amina" }
    },
    "messages": [{ "role": "user", "content": "My order is late." }]
  }'

We fill in the variables and put the prompt first in the conversation, as its system message, before the call reaches the model. The prompt counts toward the model’s context and your AI units like any other input.

With OpenAI’s SDKs, send prompt as an extra field of the request, such as extra_body in Python.

Change a prompt

Edit the instructions in the console and select Save as version N. Every save is a new version, and old versions never change, so you can see what changed and when.

• Without a version, a call uses the newest. After a save, calls can use the previous version for up to a minute.
• With a version, such as "version": 3, a call always uses that one. Pin a version while you test a change, then move to the newest.
• To go back, select Restore on an older version. Its instructions are saved as a new version, so history is kept.

Keep them safe

• Only your code chooses a prompt. Nothing in what your users type is read as a prompt name, so a user cannot pull in another prompt.
• Values fill variables exactly as sent. Treat what users type as their words, not instructions: keep it in messages rather than in a variable where you can.
• A model can repeat its instructions if asked. Do not put secrets, such as passwords or API keys, in a prompt.

When a call is refused