> ## Documentation Index
> Fetch the complete documentation index at: https://dev-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.

<Info>This is in development. Details may change before it is available.</Info>

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_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) 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.