> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altrum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

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

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.

```bash theme={null}
curl https://api.altrum.ai/v1/chat/completions \
  -H "Authorization: Bearer $ALTRUM_VIRTUAL_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](/guardrails/at-runtime.md) 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.