Skip to the content

Read a Prompt template version

GET /v1/prompt-templates/{prompt_template_id}/versions/{version}

Property	Value
Operation	`get_prompt_template_version`
Group	Prompt templates
Scope	`prompts:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A configuration read; a Prompt template is not Call content.
Released in	1.55.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the prompts:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/prompt-templates/ptpl_.../versions/1" \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/prompt-templates/ptpl_.../versions/1`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/prompt-templates/ptpl_.../versions/1",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`prompt_template_id`	path	PromptTemplateId	yes	The id of a Prompt template: `ptpl_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`version`	path	integer	yes	A version number, from 1.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	PromptTemplateVersion
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is PromptTemplateVersion.

Field	Type	Required	Description
`acknowledged_warnings`	array of PromptLintCode	yes	The warning codes the publisher acknowledges (1.55.0): each warning that needs an acknowledgement (`PROMPT_ACKNOWLEDGE_CODES`) must be listed, and the Audit event of the publish records the list. A code listed without a finding is kept and has no effect.
`active`	boolean	yes	True for the active version: the one an Agent publish pins when its `prompt` names none, or, for an Organization layer, the one dispatch resolves.
`allow_terms`	array of PromptAllowTerm	yes	Staff and place names that `phi_literal` does not report (1.55.0), at most 100 of at most 100 characters.
`constants`	PromptConstants	yes
`content_sha256`	string	yes	The SHA-256 of the canonical variants, declarations and constants, in lowercase hex.
`declarations`	PromptDeclarations	yes
`include_organization_layer`	boolean	yes
`layer`	PromptLayer	yes
`lint`	array of PromptLintFinding	yes	The warnings the publish lint returned (1.55.0); a version holds no error finding, because an error refuses the publish.
`max_rendered_tokens`	integer	yes	The longest render of any variant the declared bounds allow, estimated at 4 characters a token (a target until each model family's tokenizer is measured); checked at publish against the smallest context window of the chain (`length_exceeded`).
`notes`	string or null	yes
`object`	`"prompt_template_version"`	yes
`prompt_template_id`	PromptTemplateId	yes
`published_at`	Timestamp	yes
`published_by`	ActorRef	yes
`purpose`	PromptPurpose	yes
`source_revision`	integer	yes	The draft revision this version was published from.
`status`	PromptTemplateVersionStatus	yes
`variants`	PromptVariants	yes
`version`	integer	yes	The snapshot number, from 1.