Prompts

Use a stored prompt in a call with the prompt field. See Chat completions and Use stored prompts.

Reading prompts needs View usage and limits. Creating, changing, and deleting them is for people with Developer access or more, from the console; API keys cannot.

List prompts

[
  {
    "name": "support-agent",
    "description": "Help desk",
    "version": 3,
    "variables": ["customer"],
    "updatedBy": "01m3c081d2wj4g63qcr53pa1yh",
    "updatedAt": "2026-09-29T10:15:00Z"
  }
]

Read a prompt

{
  "name": "support-agent",
  "description": "Help desk",
  "version": 3,
  "content": "You help {{customer}} with their orders.",
  "variables": ["customer"],
  "createdBy": "01m3c081d2wj4g63qcr53pa1yh",
  "createdAt": "2026-09-20T08:00:00Z",
  "updatedBy": "01m3c081d2wj4g63qcr53pa1yh",
  "updatedAt": "2026-09-29T10:15:00Z",
  "versions": [
    {
      "version": 3,
      "createdBy": "01m3c081d2wj4g63qcr53pa1yh",
      "createdAt": "2026-09-29T10:15:00Z"
    }
  ]
}

versioninteger

The newest version, which calls use when they do not pin one.

contentstring

The newest version’s instructions.

variablesarray

Every {{name}} in the instructions, once each, in order.

versionsarray

Every version, newest first.

Read an older version

The answer has version, content, variables, createdBy, and createdAt.

Create a prompt

{
  "name": "support-agent",
  "description": "Help desk",
  "content": "You help {{customer}} with their orders."
}

namestringRequired

1 to 63 lowercase letters, digits, and hyphens, starting with a letter or digit. It cannot change later.

descriptionstring

Up to 500 characters, for your team.

contentstringRequired

The instructions, up to 32 KB, with up to 50 variables written as {{name}}.

The answer is 201 with the prompt, at version 1. A name already in use is refused with prompt_exists.

Save a new version

Send description and content, as above. The answer is the prompt, with its new version.

Delete a prompt

Deletes every version. The answer is 204, and calls that use the prompt are refused with prompt_not_found. A prompt that a task uses is refused with prompt_in_use; change or delete the task first.