Prompts

Keep your organization’s prompts in Altrum, with versions, and use them from any request.

This is in development. Details may change before it is available.

The prompt repository keeps the prompts your applications use in one governed place, instead of in each application’s code.

• A prompt belongs to your organization and has numbered versions: 1, 2, 3 and so on. A version never changes once saved. To change a prompt you save a new version, and the latest is the one used unless a request names another.
• A prompt is a list of messages, each a system, user or assistant line of text, up to 50 of them. A version can also set a temperature, a top-p value and a limit on the length of the answer. These are defaults: whatever the request sends wins.
• Any key in your organization can use any of its prompts. No other organization can, and another organization’s prompt reads exactly like one that does not exist.

Create and change a prompt

Owners and admins open AI Gateway, then Prompts, and choose Create prompt. Give it a name and its messages: each is from System, User or Assistant, and Add a message adds another. Under Defaults, a Temperature (0 to 2), a Top-p (0 to 1) and a Longest answer in tokens are optional. What changed is an optional note for the people who read the history.

A prompt’s page shows its Prompt id, to copy into your requests, and every version, newest first, with the latest marked Latest. New version starts from the latest version’s messages and saves the change as the next number; requests that name no version use it straight away. Delete deletes the prompt and all its versions, and requests that name it are refused until they stop sending it.

Everyone who can see the AI Gateway can read prompts.

Use a prompt in a request

Name the prompt in a header of a chat completions or Responses request:

Header	Meaning
x-alt-prompt-id	The prompt’s id, shown on its page in AI Gateway, then Prompts.
x-alt-prompt-version	Optional. A whole version number, such as 2. Leave it out for the latest version.

Altrum adds the prompt’s messages before the messages in your request. If your request has a system message of its own, both are sent, the prompt’s first.

curl https://api.altrum.ai/v1/chat/completions \
  -H "Authorization: Bearer $ALTRUM_KEY" \
  -H "x-alt-prompt-id: $PROMPT_ID" \
  -H "x-alt-prompt-version: 2" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Where is my order?"}]}'

Guardrails check the request with the prompt included, so a prompt cannot carry text your guardrails would block.

When the prompt cannot be used

The request is not sent to the model provider.

Status	Code	Message
404	prompt_not_found	No prompt matches the x-alt-prompt-id and x-alt-prompt-version you sent. Check the id and version in your AI Gateway prompts, or remove the headers.
400	invalid_prompt_version	The x-alt-prompt-version header must be a whole version number, such as 2. Remove it to use the latest version.