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

# REST API

> Manage Endprompt resources with standard HTTP requests

The Admin REST API provides full CRUD access to endpoints, prompts, and execution data. It follows standard REST conventions with JSON request/response bodies.

## Base URL

```
https://api.endprompt.app/admin/v1
```

All admin API routes are prefixed with `/admin/v1/`.

## Authentication

Include your admin API key in every request:

```bash theme={null}
curl -X GET https://api.endprompt.app/admin/v1/endpoints \
  -H "x-api-key: epa_your_admin_key_here"
```

See [Admin API Keys](/admin-api/authentication) for details on creating and managing keys.

## Response Format

All responses use a consistent wrapper:

```json theme={null}
{
  "succeeded": true,
  "messages": ["Endpoint created successfully"],
  "data": { ... }
}
```

| Field       | Type         | Description                          |
| ----------- | ------------ | ------------------------------------ |
| `succeeded` | boolean      | Whether the operation was successful |
| `messages`  | string\[]    | Status messages or error details     |
| `data`      | object/array | The response payload                 |

## Endpoints

### List Endpoints

```bash theme={null}
GET /admin/v1/endpoints
```

Optional query parameters:

| Parameter    | Type   | Description           |
| ------------ | ------ | --------------------- |
| `search`     | string | Filter by name        |
| `visibility` | string | `Public` or `Private` |

### Get Endpoint

```bash theme={null}
GET /admin/v1/endpoints/{id}
```

Returns full endpoint details including input and output field definitions.

### Create Endpoint

```bash theme={null}
POST /admin/v1/endpoints
```

```json theme={null}
{
  "name": "Text Summarizer",
  "path": "/api/v1/summarize",
  "description": "Summarizes long text into bullet points",
  "visibility": "Private"
}
```

### Update Endpoint

```bash theme={null}
PUT /admin/v1/endpoints/{id}
```

Supports partial updates — only include the fields you want to change:

```json theme={null}
{
  "description": "Updated description"
}
```

### Delete Endpoint

```bash theme={null}
DELETE /admin/v1/endpoints/{id}
```

Soft-deletes the endpoint. It can be restored later.

### Add Input Field

```bash theme={null}
POST /admin/v1/endpoints/{id}/input-fields
```

```json theme={null}
{
  "name": "text",
  "dataType": "string",
  "isRequired": true,
  "description": "The text to summarize",
  "maxLength": 10000
}
```

For image inputs:

```json theme={null}
{
  "name": "photo",
  "dataType": "image",
  "isRequired": true,
  "description": "The image to analyze"
}
```

### Add Output Field

```bash theme={null}
POST /admin/v1/endpoints/{id}/output-fields
```

```json theme={null}
{
  "name": "summary",
  "dataType": "string",
  "description": "The summarized text"
}
```

For image outputs (signals image generation):

```json theme={null}
{
  "name": "generated_image",
  "dataType": "image",
  "description": "The generated image",
  "exampleValue": "{\"size\": \"1024x1024\", \"quality\": \"high\"}"
}
```

<Note>
  The `exampleValue` on image output fields stores default generation config as JSON. These defaults can be overridden per-prompt via Custom Parameters.
</Note>

## Prompts

### List Prompts

```bash theme={null}
GET /admin/v1/prompts?endpointId={endpointId}
```

| Parameter    | Type   | Description                                    |
| ------------ | ------ | ---------------------------------------------- |
| `endpointId` | guid   | **Required.** The endpoint to list prompts for |
| `status`     | string | Filter by status: `Draft`, `Live`, `Archived`  |
| `search`     | string | Search by prompt name                          |

### Get Prompt

```bash theme={null}
GET /admin/v1/prompts/{id}
```

Returns full prompt details including the Liquid template content.

### Create Prompt

```bash theme={null}
POST /admin/v1/prompts
```

```json theme={null}
{
  "endpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Summarizer v1",
  "template": "Summarize the following text:\n\n{{ inputs.text }}\n\nReturn JSON with a 'summary' field.",
  "llmModel": "gpt-4o",
  "temperature": 30,
  "maxTokens": 500
}
```

New prompts are created in **Draft** status.

### Update Prompt

```bash theme={null}
PUT /admin/v1/prompts/{id}
```

Supports partial updates. If the template changes, a new version is created automatically:

```json theme={null}
{
  "template": "Updated template with {{ inputs.text }}",
  "changeNotes": "Improved output formatting"
}
```

### Prompt Lifecycle

Prompts follow a status workflow: **Draft → Live → Archived**.

| Action      | Endpoint                                  | Description                             |
| ----------- | ----------------------------------------- | --------------------------------------- |
| Promote     | `POST /admin/v1/prompts/{id}/promote`     | Draft → Live                            |
| Set Default | `POST /admin/v1/prompts/{id}/set-default` | Make this the endpoint's default prompt |
| Archive     | `POST /admin/v1/prompts/{id}/archive`     | Remove from active use                  |
| Unarchive   | `POST /admin/v1/prompts/{id}/unarchive`   | Restore to Draft                        |
| Duplicate   | `POST /admin/v1/prompts/{id}/duplicate`   | Clone as a new Draft                    |

<Note>
  Only **Live** prompts can be set as the endpoint default. Promote a Draft prompt before setting it as default.
</Note>

### Prompt Versions

```bash theme={null}
# List all versions
GET /admin/v1/prompts/{id}/versions

# Get specific version
GET /admin/v1/prompts/{id}/versions/{versionNumber}

# Restore a version as a new Draft
POST /admin/v1/prompts/{id}/versions/{versionNumber}/restore
```

### Validate Template

Check a Liquid template for syntax errors and unknown variables:

```bash theme={null}
POST /admin/v1/prompts/validate
```

```json theme={null}
{
  "endpointId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "template": "Summarize: {{ inputs.text }}"
}
```

### List Available Models

```bash theme={null}
GET /admin/v1/prompts/models
```

Returns all LLM models with capabilities (reasoning, streaming, tools, JSON mode), context windows, and pricing.

## Execution

### Execute Endpoint

```bash theme={null}
POST /api/v1/{endpoint-path}
```

```json theme={null}
{
  "text": "Your content here"
}
```

<Tip>
  Admin keys (`epa_`) can execute endpoints, so you can use a single key for both management and testing.
</Tip>

## Logs & Stats

### List Execution Logs

```bash theme={null}
GET /admin/v1/logs
```

| Parameter    | Type   | Description                             |
| ------------ | ------ | --------------------------------------- |
| `endpointId` | guid   | Filter by endpoint                      |
| `source`     | string | `Api`, `TestPage`, `Internal`           |
| `page`       | int    | Page number (default: 1)                |
| `pageSize`   | int    | Results per page (default: 20, max: 50) |

### Get Execution Log

```bash theme={null}
GET /admin/v1/logs/{id}
```

Returns full execution details including rendered prompt, raw LLM response, and parsed output.