Skip to main content
Base URL: https://api.zeroeval.com All requests require a Bearer token: 
Authorization: Bearer YOUR_ZEROEVAL_API_KEY

​
Get Prompt

GET /v1/prompts/{prompt_slug}
Fetch the current version of a prompt by its slug.
Query ParameterTypeDefaultDescription
versionint—Fetch a specific version number
tagstring"latest"Tag to fetch ("production", "latest", etc.)
curl https://api.zeroeval.com/v1/prompts/support-bot \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY"
Response: 200 
{
  "id": "a1b2c3d4-...",
  "prompt_id": "b2c3d4e5-...",
  "content": "You are a helpful customer support agent.",
  "content_hash": "e3b0c44298fc...",
  "version": 3,
  "model_id": "gpt-4o",
  "tag": "production",
  "is_latest": true,
  "metadata": {},
  "created_at": "2025-01-15T10:30:00Z"
}

​
Fetch by tag

curl "https://api.zeroeval.com/v1/prompts/support-bot?tag=production" \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY"

​
Fetch by version number

curl "https://api.zeroeval.com/v1/prompts/support-bot?version=2" \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY"

​
Ensure Prompt Version

POST /v1/tasks/{task_name}/prompt/versions/ensure
Create a prompt version if it doesn’t already exist (idempotent by content hash). This is what ze.prompt() calls under the hood. Request body:
FieldTypeRequiredDescription
contentstringYesPrompt content
content_hashstringNoSHA-256 hash (computed server-side if omitted)
model_idstringNoModel to bind to this version
metadataobjectNoAdditional metadata
curl -X POST https://api.zeroeval.com/v1/tasks/support-bot/prompt/versions/ensure \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are a helpful customer support agent for {{company}}."
  }'
Response: 200 
{
  "id": "c3d4e5f6-...",
  "content": "You are a helpful customer support agent for {{company}}.",
  "content_hash": "a1b2c3d4...",
  "version": 1,
  "model_id": null,
  "created_at": "2025-01-15T10:30:00Z"
}

​
Get Version by Hash

GET /v1/tasks/{task_name}/prompt/versions/by-hash/{content_hash}
Fetch a specific prompt version by its SHA-256 content hash. Response: 200 (same schema as ensure)

​
Get Latest Version

GET /v1/tasks/{task_name}/prompt/latest
Fetch the latest prompt version for a task. Response: 200 (same schema as ensure)

​
Resolve Model for Version

GET /v1/prompt-versions/{version_id}/model
Get the model bound to a specific prompt version. Used by SDK integrations to auto-patch the model parameter. Response: 200 
{
  "model_id": "gpt-4o",
  "provider": "openai"
}
Returns null for model_id if no model is bound.

​
Deploy a Version (Pin Tag)

POST /projects/{project_id}/prompts/{prompt_slug}/tags/{tag}:pin
Pin a tag (e.g. production) to a specific version number. This is how you deploy a prompt version to production. Request body:
FieldTypeRequiredDescription
versionintYesVersion number to pin
curl -X POST https://api.zeroeval.com/projects/$PROJECT_ID/prompts/support-bot/tags/production:pin \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 3}'

​
List Versions

GET /projects/{project_id}/prompts/{prompt_slug}/versions
List all versions of a prompt. Response: 200 
[
  {
    "id": "c3d4e5f6-...",
    "content": "You are a helpful assistant.",
    "content_hash": "a1b2c3d4...",
    "version": 1,
    "model_id": null,
    "created_at": "2025-01-10T10:00:00Z"
  },
  {
    "id": "d4e5f6a7-...",
    "content": "You are a helpful customer support agent.",
    "content_hash": "b2c3d4e5...",
    "version": 2,
    "model_id": "gpt-4o",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

​
List Tags

GET /projects/{project_id}/prompts/{prompt_slug}/tags
List all tags and which version each is pinned to. Response: 200 
[
  { "tag": "latest", "version": 2 },
  { "tag": "production", "version": 1 }
]

​
Update Version Model

PATCH /projects/{project_id}/prompts/{prompt_slug}/versions/{version}
Update the model bound to a version. Request body:
FieldTypeDescription
model_idstringModel identifier to bind

​
Submit Completion Feedback

POST /v1/prompts/{prompt_slug}/completions/{completion_id}/feedback
See Feedback API Reference for the full specification.