---
title: "Render a prompt template"
method: POST
path: "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/render"
tags: ["Versions", "AI"]
---

# Render a prompt template

`POST /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/render`

## Request

- The document declares no server URL.
- Auth: none declared

Renders a prompt template artifact by substituting the provided variables into the template.
The artifact must be of type `PROMPT_TEMPLATE`. Variables are validated against the template's
variable schema before rendering.

This operation can fail for the following reasons:

* No artifact with this `artifactId` exists (HTTP error `404`)
* No version with this `version` exists (HTTP error `404`)
* The artifact is not a PROMPT_TEMPLATE (HTTP error `400`)
* Required variables are missing or have invalid types (HTTP error `400`)
* A server error occurred (HTTP error `500`)

## Request body

- RenderPromptRequest: Request body for rendering a prompt template with variable substitution.
  - `variables` object, required: A map of variable names to their values. These will be substituted into the prompt template.

## Response `200`

The rendered prompt template.

- RenderPromptResponse: Response from rendering a prompt template.
  - `rendered` string, required: The rendered prompt with all variables substituted.
  - `groupId` string: The group ID of the artifact.
  - `artifactId` string: The artifact ID.
  - `version` string: The version of the artifact that was rendered.
  - `validationErrors` RenderValidationError[]: Any validation errors encountered when validating variables against the template schema.
    - `variableName` string, required: The name of the variable that failed validation.
    - `message` string, required: A description of the validation error.
    - `expectedType` string: The expected type of the variable.
    - `actualType` string: The actual type that was provided.

## Other responses

- `400`: Common response for all operations that can return a `400` error.
- `401`: Common response for all operations that can return a `401` error indicating authentication is required.
- `403`: Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
- `404`: Common response for all operations that can return a `404` error.
- `500`: Common response for all operations that can fail with an unexpected server error.

## Changes

- **2026-10-31** `ff9684af2aad`: 25 info
  - added the optional property `ruleViolation/causes/items/code` to the response with the `400` status
  - added the optional property `ruleViolation/causes/items/code` to the response with the `401` status
  - added the optional property `ruleViolation/causes/items/code` to the response with the `403` status
  - added the optional property `ruleViolation/causes/items/code` to the response with the `404` status
  - …21 more
- **2026-10-29** `f17f5df4e79c`: 5 info
  - added the optional property `ruleViolation` to the response with the `400` status
  - added the optional property `ruleViolation` to the response with the `401` status
  - added the optional property `ruleViolation` to the response with the `403` status
  - added the optional property `ruleViolation` to the response with the `404` status
  - …1 more
- **2026-01-23** `bcddbdaed574`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v3/changes/groups/:groupId/artifacts/:artifactId/versions/:versionExpression/render/post.md)

---

[API](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v3.md) - [All operations](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v3/revisions/ff9684af2aad?raw)