> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroeval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API for managing prompts, versions, and deployments

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 Parameter | Type     | Default    | Description                                     |
| --------------- | -------- | ---------- | ----------------------------------------------- |
| `version`       | `int`    | —          | Fetch a specific version number                 |
| `tag`           | `string` | `"latest"` | Tag to fetch (`"production"`, `"latest"`, etc.) |

```bash theme={null}
curl https://api.zeroeval.com/v1/prompts/support-bot \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY"
```

**Response:** 200

```json theme={null}
{
  "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

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

### Fetch by version number

```bash theme={null}
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:**

| Field          | Type     | Required | Description                                    |
| -------------- | -------- | -------- | ---------------------------------------------- |
| `content`      | `string` | Yes      | Prompt content                                 |
| `content_hash` | `string` | No       | SHA-256 hash (computed server-side if omitted) |
| `model_id`     | `string` | No       | Model to bind to this version                  |
| `metadata`     | `object` | No       | Additional metadata                            |

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:**

| Field     | Type  | Required | Description           |
| --------- | ----- | -------- | --------------------- |
| `version` | `int` | Yes      | Version number to pin |

```bash theme={null}
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

```json theme={null}
[
  {
    "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

```json theme={null}
[
  { "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:**

| Field      | Type     | Description              |
| ---------- | -------- | ------------------------ |
| `model_id` | `string` | Model identifier to bind |

***

## Submit Completion Feedback

```
POST /v1/prompts/{prompt_slug}/completions/{completion_id}/feedback
```

See [Feedback API Reference](/feedback/api-reference#completion-feedback) for the full specification.