> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a prompt
> Create a new prompt with an initial version.
**Payload Requirements**
- The prompt name must be unique within the given space.
- At least one message is required.
This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).
## OpenAPI
````yaml https://api.arize.com/v2/spec.yaml post /v2/prompts
openapi: 3.0.3
info:
title: Arize REST API
version: 2.0.0
description: |
API specification for the backend data server. The API is hosted globally
at https://api.arize.com/v2 or in your own environment.
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- description: Global
url: https://api.arize.com
- description: Regional
url: https://api.{region}.arize.com
variables:
region:
default: eu-west-1a
enum:
- eu-west-1a
- ca-central-1a
- description: Custom Host
url: https://{host}
variables:
host:
default: api.arize.com
security:
- bearerAuth: []
tags:
- name: AI Integrations
description: |
AI integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
entire account, a specific organization, or a specific space.
- name: Annotation Configs
description: >
Annotation configs allow you to define consistent annotation schemas that
can be reused across your workspace, ensuring evaluations are structured
and
comparable over time.
- name: Annotation Queues
description: >
Annotation queues help you organize and manage human evaluation workflows.
Use queues to assign spans or examples to annotators for review and
labeling.
- name: API Keys
description: >
API keys are used to authenticate requests to the Arize API. List your
keys
to view metadata; the raw secret is never returned after creation.
- name: Datasets
description: |
Datasets are structured, version-controlled example collections you use to
run, evaluate, and track LLM experiments.
- name: Evaluators
description: >
Evaluators are reusable evaluation configurations used to assess the
quality
of LLM outputs. They can be template-based (using LLM judges) or
code-based.
- name: Experiments
description: >
Experiments let you systematically test prompt/model changes using
datasets,
tasks, and evaluators.
- name: Integrations
description: >
Integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
PagerDuty, Slack), and
your own agents. Integrations can be scoped to the entire account, a
specific
organization, or a specific space.
- name: Organizations
description: >
Organizations are top-level containers within an Arize AX account for
grouping spaces.
- name: Projects
description: |
Projects represent LLM applications being monitored in Arize where you can
observe traces and spans.
- name: Prompts
description: >
Prompts are reusable, versioned templates for LLM interactions. Use
prompts
to standardize and manage how you interact with LLMs across your
application.
- name: Resource Restrictions
description: |
Endpoints for restricting and unrestricting resources (projects, models).
- name: Role Bindings
description: |
Role bindings assign a role to a user on a resource. REST currently
supports space- and project-scoped bindings.
- name: Roles
description: >
Roles define sets of permissions that can be assigned to users within an
account. Create custom roles to tailor access control to your team's
needs.
- name: Spaces
description: >
Spaces are containers within an organization for grouping related
projects,
datasets, and experiments, enabling collaboration or isolated
experimentation
with role-based access control.
- name: Spans
description: |
Spans represent individual operations within a trace. A span captures the
timing, status, and attributes of a single operation in your application.
- name: Tasks
description: |
Tasks are configurable units of work that tie one or more evaluators to a
data source (project or dataset). Use tasks to automate evaluation of LLM
outputs, with support for continuous evaluation and backfill runs.
- name: Users
description: >
Users represent members of an account. The Users endpoints allow creating,
listing, updating (display name), and removing users from the account
programmatically.
paths:
/v2/prompts:
post:
tags:
- Prompts
summary: Create a prompt
description: >
Create a new prompt with an initial version.
**Payload Requirements**
- The prompt name must be unique within the given space.
- At least one message is required.
This endpoint is in beta, read more
[here](https://arize.com/docs/ax/rest-reference#api-version-stages).
operationId: prompts_create
requestBody:
$ref: '#/components/requestBodies/CreatePromptRequestBody'
responses:
'201':
$ref: '#/components/responses/PromptWithVersion'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
requestBodies:
CreatePromptRequestBody:
description: Body containing prompt creation parameters with an initial version
required: true
content:
application/json:
schema:
required:
- space_id
- name
- version
type: object
properties:
space_id:
type: string
description: ID of the space to create the prompt in
name:
type: string
description: Name of the prompt (must be unique within the space)
description:
type: string
description: >-
Description of the prompt. Optional. If omitted, the prompt
has no description.
version:
$ref: '#/components/schemas/PromptVersionCreateRequest'
example:
space_id: U3BhY2U6MTIzOmFiY2Q=
name: My Prompt
description: A helpful assistant prompt
version:
commit_message: Initial version
input_variable_format: f_string
provider: open_ai
model: gpt-4
messages:
- role: system
content: You are a helpful assistant.
- role: user
content: Hello, {name}!
responses:
PromptWithVersion:
description: A prompt object with a resolved version
content:
application/json:
schema:
$ref: '#/components/schemas/PromptWithVersion'
example:
id: prompt_001
name: My Prompt
description: A prompt for customer support
space_id: space_12345
created_at: '2024-01-01T12:00:00Z'
updated_at: '2024-01-02T12:00:00Z'
created_by_user_id: user_12345
version:
id: pv_001
prompt_id: prompt_001
commit_hash: abc123def456
commit_message: Initial version
messages:
- role: system
content: You are a helpful assistant.
- role: user
content: Hello, {name}!
input_variable_format: f_string
provider: open_ai
model: gpt-4
invocation_params: {}
provider_params: {}
created_at: '2024-01-01T12:00:00Z'
created_by_user_id: user_12345
labels: []
BadRequest:
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 400
title: Invalid request parameters
detail: The 'name' field is required and must be a non-empty string.
instance: /resource
type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
Unauthorized:
description: Authentication is required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 401
title: Authentication required
detail: You must be authenticated to access this resource.
instance: /resource
type: >-
https://arize.com/docs/ax/rest-reference/errors#authentication-required
Forbidden:
description: Insufficient permissions to access this resource
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 403
title: Access forbidden
detail: You do not have permission to access this resource.
instance: /resource/12345
type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
Conflict:
description: Resource conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 409
title: Resource conflict
detail: A resource with the given identifier already exists.
instance: /resource
type: https://arize.com/docs/ax/rest-reference/errors#resource-conflict
UnprocessableEntity:
description: Unprocessable entity
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 422
title: Unprocessable Entity
detail: One or more fields failed validation.
instance: /resource/12345
type: >-
https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
RateLimitExceeded:
description: Rate limit exceeded
headers:
Retry-After:
description: |
When throttled (429), how long to wait before retrying. Value is
either a delta-seconds integer.
schema:
type: integer
minimum: 0
example: 42
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
status: 429
title: Rate limit exceeded
detail: >-
You have exceeded the allowed number of requests. Please try again
later.
instance: /resource
type: >-
https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
schemas:
PromptVersionCreateRequest:
type: object
required:
- commit_message
- provider
- messages
description: Initial version configuration for a new prompt
properties:
commit_message:
type: string
description: Commit message describing this version
input_variable_format:
allOf:
- $ref: '#/components/schemas/InputVariableFormat'
default: f_string
description: >-
Format for input variables in the prompt messages. Defaults to
`f_string` if not provided.
provider:
$ref: '#/components/schemas/LlmProvider'
model:
type: string
description: >-
The model to use for the call. Optional. If omitted, no default
model is set on the prompt version.
messages:
type: array
minItems: 1
description: The messages that make up the prompt template
items:
$ref: '#/components/schemas/LLMMessage'
invocation_params:
$ref: '#/components/schemas/InvocationParams'
description: >-
Parameters for the LLM invocation. Optional. Defaults to empty (no
invocation parameters).
provider_params:
$ref: '#/components/schemas/ProviderParams'
description: >-
Provider-specific parameters. Optional. Defaults to empty (no
provider-specific parameters).
additionalProperties: false
PromptWithVersion:
allOf:
- $ref: '#/components/schemas/Prompt'
- type: object
required:
- version
properties:
version:
$ref: '#/components/schemas/PromptVersion'
description: >
A prompt with a resolved version. Returned by Create Prompt and Get
Prompt.
The version is the initial version on create, or the resolved version
(latest, by ID, or by label) on get.
additionalProperties: false
Problem:
type: object
description: RFC 9457 Problem Details
properties:
title:
type: string
description: A short, human-readable summary of the problem type
status:
type: integer
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem
type:
type: string
format: uri-reference
description: A URI reference that identifies the problem type
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem
instance:
type: string
format: uri-reference
description: >-
A URI reference that identifies the specific occurrence of the
problem
required:
- title
- status
additionalProperties: false
InputVariableFormat:
type: string
enum:
- f_string
- mustache
- none
description: >
The format for input variables in the prompt messages. Defaults to
`f_string` if not provided.
- `f_string`: Single curly braces ({variable_name})
- `mustache`: Double curly braces ({{variable_name}})
- `none`: **Deprecated.** Treated as `f_string`. Will be removed in a
future version.
LlmProvider:
type: string
enum:
- open_ai
- azure_open_ai
- aws_bedrock
- vertex_ai
- anthropic
- custom
description: The LLM provider to use
LLMMessage:
type: object
description: A message in the prompt template
required:
- role
properties:
role:
$ref: '#/components/schemas/MessageRole'
content:
type: string
nullable: true
description: The content of the message
tool_call_id:
type: string
description: The ID of the tool call this message is responding to
tool_calls:
type: array
description: Tool calls generated by the model
items:
$ref: '#/components/schemas/ToolCall'
InvocationParams:
type: object
description: Parameters for the LLM invocation
properties:
temperature:
type: number
description: Sampling temperature (higher = more random)
max_tokens:
type: integer
description: Maximum number of tokens to generate
max_completion_tokens:
type: integer
description: Maximum number of completion tokens to generate
top_p:
type: number
description: Nucleus sampling parameter
frequency_penalty:
type: number
description: Frequency penalty (-2.0 to 2.0)
presence_penalty:
type: number
description: Presence penalty (-2.0 to 2.0)
stop:
type: array
items:
type: string
description: Stop sequences
response_format:
allOf:
- $ref: '#/components/schemas/ResponseFormat'
description: >-
Response format configuration. Optional. When omitted, no structured
output constraint is applied (the provider's default plain-text
behavior is used).
tool_config:
allOf:
- $ref: '#/components/schemas/ToolConfig'
description: >-
Tool configuration for the LLM invocation. Optional. When omitted,
no tools are made available to the model.
top_k:
type: integer
description: >-
Top-K sampling parameter. A top-K of 1 means the next selected token
is the most probable (greedy decoding).
thinking_level:
type: string
description: >-
Controls how much reasoning the model performs before responding.
Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
thinking_budget:
type: integer
description: >-
Maximum tokens the model may use for internal reasoning. Supported
by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768
(Pro). Set 0 to disable thinking on Flash models.
reasoning_effort:
type: string
description: >-
Controls how much reasoning the model performs before responding.
Supported by OpenAI o-series and GPT-5 models. o-series: 'low' |
'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' |
'xhigh'.
verbosity:
type: string
description: >-
Controls the verbosity of model output. Supported by OpenAI GPT-5
series. Accepted values: 'low' | 'medium' | 'high'.
additionalProperties: true
ProviderParams:
type: object
description: Provider-specific parameters
properties:
azure_params:
type: object
description: Azure OpenAI specific parameters
properties:
azure_deployment_name:
type: string
description: The Azure deployment name
azure_openai_endpoint:
type: string
description: The Azure OpenAI endpoint URL
azure_openai_version:
type: string
description: The Azure OpenAI API version
anthropic_headers:
type: object
description: Anthropic-specific headers
properties:
anthropic_beta:
type: array
description: Anthropic beta feature flags
items:
type: string
nullable: true
nullable: true
anthropic_version:
type: string
description: Anthropic API version
bedrock_options:
type: object
description: AWS Bedrock options
properties:
use_converse_endpoint:
type: boolean
default: false
description: >-
Whether to use the AWS Bedrock Converse endpoint. Defaults to
`false`.
region:
type: string
description: Region for the model deployment
additionalProperties: true
Prompt:
type: object
required:
- id
- name
- space_id
- created_at
- updated_at
- created_by_user_id
properties:
id:
type: string
description: The prompt ID
name:
type: string
description: The prompt name
description:
type: string
nullable: true
description: The prompt description
space_id:
type: string
description: The space ID the prompt belongs to
created_at:
type: string
format: date-time
description: When the prompt was created
updated_at:
type: string
format: date-time
description: When the prompt was last updated
created_by_user_id:
type: string
description: The user ID of the user who created the prompt
description: >
A prompt is a reusable template for LLM interactions. Prompts can be
versioned
and labeled to track changes over time. Use prompts to standardize how
you
interact with LLMs across your application.
additionalProperties: false
PromptVersion:
type: object
required:
- id
- prompt_id
- commit_hash
- commit_message
- messages
- input_variable_format
- provider
- model
- created_at
- created_by_user_id
properties:
id:
type: string
description: The prompt version ID
prompt_id:
type: string
description: The prompt ID this version belongs to
commit_hash:
type: string
description: The commit hash of this version
commit_message:
type: string
description: The commit message describing the changes in this version
messages:
type: array
description: The messages that make up the prompt template
items:
$ref: '#/components/schemas/LLMMessage'
input_variable_format:
$ref: '#/components/schemas/InputVariableFormat'
provider:
$ref: '#/components/schemas/LlmProvider'
model:
type: string
description: The model to use for the call
invocation_params:
allOf:
- $ref: '#/components/schemas/InvocationParams'
description: >-
LLM invocation parameters for this version. When absent, no
invocation parameters were set on this version.
provider_params:
allOf:
- $ref: '#/components/schemas/ProviderParams'
description: >-
Provider-specific parameters for this version. When absent, no
provider-specific parameters were set on this version.
created_at:
type: string
format: date-time
description: When the version was created
created_by_user_id:
type: string
description: The user ID of the user who created this version
labels:
type: array
items:
type: string
description: >-
Label names currently pointing to this version (e.g., "production",
"staging"). Labels are case-sensitive.
description: >
A prompt version represents a specific snapshot of a prompt's
configuration.
Each version captures the messages, model settings, and parameters at a
point
in time. Versions are immutable once created and are identified by a
commit hash.
additionalProperties: false
MessageRole:
type: string
enum:
- user
- assistant
- system
- tool
description: The role of the message author
ToolCall:
type: object
description: A tool call generated by the model
required:
- type
- function
properties:
id:
type: string
description: The ID of the tool call
type:
$ref: '#/components/schemas/ToolCallType'
function:
$ref: '#/components/schemas/ToolCallFunction'
ResponseFormat:
type: object
description: Response format configuration
properties:
type:
allOf:
- $ref: '#/components/schemas/ResponseFormatType'
default: text
description: The response format type. Defaults to `text` if not specified.
json_schema:
type: object
description: JSON schema configuration (when type is json_schema)
properties:
name:
type: string
description: The name of the JSON schema
description:
type: string
description: A description of the JSON schema
schema:
type: object
description: The JSON schema object
strict:
type: boolean
default: false
description: >-
Whether to enforce strict schema validation. Defaults to
`false`.
ToolConfig:
type: object
description: Tool configuration for the LLM invocation
properties:
tools:
type: array
description: List of tool definitions available to the model
items:
type: object
tool_choice:
description: Tool choice configuration
ToolCallType:
type: string
enum:
- function
description: The type of tool call
ToolCallFunction:
type: object
description: The function to call
required:
- name
- arguments
properties:
name:
type: string
description: The name of the function
arguments:
type: string
description: The arguments to the function as a JSON string
ResponseFormatType:
type: string
enum:
- text
- json_object
- json_schema
description: The response format type
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat:
description: >
Most Arize AI endpoints require authentication. For those endpoints that
require authentication, include your API key in the request header using
the format
``` Authorization: Bearer
```
````