Prompt Templates

GET /api/orgs/{org_id}/prompt-templates

List Prompt Templates

List prompt templates for the organization.

Omit limit to get every template; total is the full count either way.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized templates.

Responses

Status	Description	Body
200	Successful Response	Page_PromptTemplateResponse_
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/prompt-templates

Create Prompt Template

Create a new prompt template. Requires admin/owner role.

fields (optional) defines an extraction schema — when present, the template runs as structured extraction instead of free-text generation.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
description	string	no
fields	PromptFieldSchema[]	no
file_input_mode	"auto" | "image" | "text" | "both"	no
model	string	no
name	string	yes
post_processing_instructions	string	no
provider	string	no
reasoning_effort	string	no
tags	string[]	no
text	string	no

Responses

Status	Description	Body
201	Successful Response	PromptTemplateResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/prompt-templates/{id_or_slug}

Get Prompt Template

Get a prompt template by ID or slug.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	PromptTemplateResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/prompt-templates/{id_or_slug}/test

Test Prompt Template

Stream a test execution of a prompt template. Requires admin/owner role.

Drives BOTH modes via the unified stream_prompt_test runner: a plain prompt (no fields on the active revision) streams free-text token/done events; a schema-bearing prompt streams the structured extracting/result/post_processing/done events and requires material input via input_text or input_url.

Parameters

Name	In	Type	Required	Description
id_or_slug	path	string	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
attachments	PromptTestAttachment[]	no
file_input_mode	"auto" | "image" | "text" | "both"	no
input_text	string	no
input_url	string	no
model	string	yes
provider	string	yes
reasoning_effort	string	no
variables	object	no

Responses

Status	Description	Body
200	Successful Response	object
422	Validation Error	HTTPValidationError

PUT /api/orgs/{org_id}/prompt-templates/{template_id}

Update Prompt Template

Update a prompt template by ID or slug. Requires admin/owner role.

Passing text, fields, or post_processing_instructions creates a new revision (versioned together as one snapshot).

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
template_id	path	string	yes

Request body (required)

Field	Type	Required	Description
description	string	yes
fields	PromptFieldSchema[]	no
file_input_mode	"auto" | "image" | "text" | "both"	yes
model	string	yes
name	string	no
post_processing_instructions	string	no
provider	string	yes
reasoning_effort	string	yes
tags	string[]	no
text	string	no

Responses

Status	Description	Body
200	Successful Response	PromptTemplateResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/prompt-templates/{template_id}

Delete Prompt Template

Soft-delete a prompt template by ID or slug. Requires admin/owner role.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
template_id	path	string	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/prompt-templates/{template_id}/revisions

List Prompt Template Revisions

List all revisions for a prompt template (by ID or slug).

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
template_id	path	string	yes

Responses

Status	Description	Body
200	Successful Response	PromptTemplateRevisionSummary[]
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/prompt-templates/{template_id}/runs

List Prompt Template Runs

List runs for a prompt template (by ID or slug).

Parameters

Name	In	Type	Required	Description
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes
template_id	path	string	yes

Responses

Status	Description	Body
200	Successful Response	PromptTemplateRunResponse[]
422	Validation Error	HTTPValidationError