Prompts endpoints
GET /api/v1/projects/{project_id}/prompt-versions/{version_id}
Section titled “GET /api/v1/projects/{project_id}/prompt-versions/{version_id}”Get a prompt version by id
The version with its prompt’s name; model_config is the version’s model advice.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
version_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: PromptVersionByIdOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/prompts
Section titled “GET /api/v1/projects/{project_id}/prompts”List prompts
Most recently changed first, with each prompt’s latest version number and labels.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
q |
query | string or null | no | Name prefix max length 128 |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no | max length 512 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_PromptListItemOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/prompts
Section titled “POST /api/v1/projects/{project_id}/prompts”Add a prompt
Store the prompt with its version 1. 409 NAME_TAKEN; 422 VALIDATION_ERROR for a
malformed template.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): PromptCreate
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: PromptOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/prompts/{name}
Section titled “DELETE /api/v1/projects/{project_id}/prompts/{name}”Delete a prompt
Delete the prompt with all its versions and labels.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/prompts/{name}
Section titled “GET /api/v1/projects/{project_id}/prompts/{name}”Get a prompt
The prompt with its latest version and labels.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: PromptOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/prompts/{name}/labels/{label}
Section titled “DELETE /api/v1/projects/{project_id}/prompts/{name}/labels/{label}”Remove a label
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
label |
path | string | yes | min length 1, max length 64 |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
PUT /api/v1/projects/{project_id}/prompts/{name}/labels/{label}
Section titled “PUT /api/v1/projects/{project_id}/prompts/{name}/labels/{label}”Point a label at a version
Create the label or move it. 422 LABEL_RESERVED for latest; 404 for a version the
prompt does not have.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
label |
path | string | yes | max length 32, pattern ^[a-z0-9][a-z0-9_-]{0,31}$ |
Request body (application/json, required): LabelSetIn
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: LabelOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/prompts/{name}/versions
Section titled “GET /api/v1/projects/{project_id}/prompts/{name}/versions”List prompt versions
Newest first.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no | max length 512 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_VersionOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/prompts/{name}/versions
Section titled “POST /api/v1/projects/{project_id}/prompts/{name}/versions”Add a prompt version
Add the next version. 409 KIND_MISMATCH when the kind differs from the prompt’s;
409 NO_CHANGES when nothing differs from the latest version; 429 RATE_LIMITED after 100
versions of the prompt in a UTC day (Retry-After is the time to midnight).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
Request body (application/json, required): VersionCreate
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: VersionOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/prompts/{name}/versions/{version}
Section titled “GET /api/v1/projects/{project_id}/prompts/{name}/versions/{version}”Get a prompt version
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
version |
path | integer | yes | min 1, max 2147483647 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: VersionOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/prompts/{name}/versions/{version}/usage
Section titled “GET /api/v1/projects/{project_id}/prompts/{name}/versions/{version}/usage”Get a prompt version’s usage
Traces, LLM calls, cost and p95 latency of the calls that used the version, last 7 days.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
name |
path | string | yes | min length 1, max length 129 |
version |
path | integer | yes | min 1, max 2147483647 |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: VersionUsageOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /v1/prompts/{name}
Section titled “GET /v1/prompts/{name}”Read a prompt version
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
name |
path | string | yes | min length 1, max length 200 |
label |
query | string or null | no | max length 64 |
version |
query | integer or null | no | min 1 |
if-none-match |
header | string or null | no |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: PromptReadOut |
| 304 | The cached version is still the one served. | none |
| 422 | Validation Error | application/json: HTTPValidationError |