Prompts

Create, manage, version, and render prompts. Prompts support four types: system-prompt, user-prompt, skill, and template. Every update creates a new version automatically.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Prompt Object

{
  "id": "prompt_abc123",
  "name": "Customer Support Agent",
  "description": "System prompt for customer support interactions",
  "type": "system-prompt",
  "content": "You are a helpful customer support agent for {{company}}. Help customers with {{topic}} questions.",
  "variables": [
    {
      "name": "company",
      "description": "Company name",
      "defaultValue": "Acme Corp",
      "required": true
    },
    {
      "name": "topic",
      "description": "Support topic area",
      "defaultValue": "general",
      "required": false
    }
  ],
  "tags": ["support", "customer-facing"],
  "currentVersion": 3,
  "ownerId": "user_456",
  "ownerName": "Jane Smith",
  "organizationId": "org_789",
  "isPublic": false,
  "sharedWith": ["user_012"],
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-02-19T14:30:00Z"
}

Version Object

{
  "id": "ver_xyz789",
  "promptId": "prompt_abc123",
  "versionNumber": 3,
  "content": "You are a helpful customer support agent for {{company}}...",
  "variables": [
    {
      "name": "company",
      "description": "Company name",
      "defaultValue": "Acme Corp",
      "required": true
    }
  ],
  "changeNote": "Updated tone to be more friendly",
  "createdAt": "2026-02-19T14:30:00Z",
  "createdBy": "user_456",
  "createdByName": "Jane Smith"
}

---

GET /api/v1/prompts

List all prompts accessible to the authenticated user. Includes owned, shared, and public prompts.

Scope: prompts:read

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 25, max: 100)
type	string	No	Filter by type: system-prompt, user-prompt, skill, template
search	string	No	Search by name (case-insensitive)
tags	string	No	Comma-separated tag filter

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "prompt_abc123",
      "name": "Customer Support Agent",
      "type": "system-prompt",
      "description": "System prompt for customer support",
      "tags": ["support"],
      "currentVersion": 3,
      "ownerName": "Jane Smith",
      "isPublic": false,
      "updatedAt": "2026-02-19T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 42
  },
  "requestId": "req_abc"
}

---

POST /api/v1/prompts

Create a new prompt. Automatically creates version 1. Variables are auto-detected from {{variableName}} patterns in content.

Scope: prompts:write

Request Body

Field	Type	Required	Description
name	string	Yes	Prompt name (max 200 characters)
type	string	Yes	One of: system-prompt, user-prompt, skill, template
content	string	Yes	Prompt content (supports {{variable}} syntax)
description	string	No	Optional description
tags	string[]	No	Array of tags
variables	object[]	No	Variable definitions with name, description, defaultValue, required

Request

{
  "name": "Data Extraction Template",
  "type": "template",
  "content": "Extract the following entities from the text:\n- {{entity_types}}\n\nText: {{input_text}}\n\nReturn as JSON.",
  "description": "General-purpose entity extraction prompt",
  "tags": ["extraction", "nlp"],
  "variables": [
    {
      "name": "entity_types",
      "description": "Comma-separated list of entity types to extract",
      "defaultValue": "person, organization, location",
      "required": true
    },
    {
      "name": "input_text",
      "description": "The text to extract entities from",
      "required": true
    }
  ]
}

Response 201 Created

{
  "success": true,
  "data": {
    "id": "prompt_def456",
    "name": "Data Extraction Template",
    "type": "template",
    "currentVersion": 1,
    "createdAt": "2026-02-19T15:00:00Z"
  },
  "requestId": "req_def"
}

---

GET /api/v1/prompts/:id

Get a specific prompt by ID. Requires read access (owner, shared, or public).

Scope: prompts:read

Response 200 OK

Returns the full Prompt Object.

---

PUT /api/v1/prompts/:id

Update a prompt. When content or variables change, a new version is created automatically. The currentVersion field is incremented.

Scope: prompts:write

Request Body

Field	Type	Required	Description
name	string	No	Updated name
description	string	No	Updated description
content	string	No	Updated content (triggers new version)
tags	string[]	No	Updated tags
variables	object[]	No	Updated variable definitions (triggers new version)
changeNote	string	No	Description of changes for the version history

Request

{
  "content": "You are a friendly customer support agent for {{company}}. Always greet the customer warmly.",
  "changeNote": "Made tone more friendly, added greeting instruction"
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "prompt_abc123",
    "currentVersion": 4,
    "updatedAt": "2026-02-19T16:00:00Z"
  },
  "requestId": "req_ghi"
}

---

DELETE /api/v1/prompts/:id

Delete a prompt and all its versions. This action cannot be undone.

Scope: prompts:write

Response 200 OK

{
  "success": true,
  "requestId": "req_jkl"
}

---

GET /api/v1/prompts/:id/versions

List all versions of a prompt, sorted by version number (newest first).

Scope: prompts:read

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "ver_3",
      "versionNumber": 3,
      "changeNote": "Updated tone to be more friendly",
      "createdBy": "user_456",
      "createdByName": "Jane Smith",
      "createdAt": "2026-02-19T14:30:00Z"
    },
    {
      "id": "ver_2",
      "versionNumber": 2,
      "changeNote": "Added company variable",
      "createdBy": "user_456",
      "createdByName": "Jane Smith",
      "createdAt": "2026-02-10T09:15:00Z"
    },
    {
      "id": "ver_1",
      "versionNumber": 1,
      "changeNote": null,
      "createdBy": "user_456",
      "createdByName": "Jane Smith",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "requestId": "req_mno"
}

---

POST /api/v1/prompts/:id/restore

Restore a previous version. This creates a new version with the content from the specified version, preserving the full history.

Scope: prompts:write

Request Body

Field	Type	Required	Description
versionNumber	integer	Yes	The version number to restore

Request

{
  "versionNumber": 2
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "prompt_abc123",
    "currentVersion": 5,
    "restoredFrom": 2
  },
  "requestId": "req_pqr"
}

---

POST /api/v1/prompts/:id/duplicate

Create a copy of an existing prompt. The new prompt has:

• The authenticated user as owner
• Name suffixed with "(Copy)"
• Version reset to 1
• All content, variables, and tags preserved

Scope: prompts:write

Response 201 Created

{
  "success": true,
  "data": {
    "id": "prompt_new789",
    "name": "Customer Support Agent (Copy)",
    "currentVersion": 1
  },
  "requestId": "req_stu"
}

---

POST /api/v1/prompts/:id/render

Render a prompt by substituting variable values into the content. Returns the rendered text without modifying the prompt.

Scope: prompts:read

Request Body

Field	Type	Required	Description
variables	object	Yes	Key-value pairs for variable substitution

Request

{
  "variables": {
    "company": "Acme Corp",
    "topic": "billing"
  }
}

Response 200 OK

{
  "success": true,
  "data": {
    "rendered": "You are a helpful customer support agent for Acme Corp. Help customers with billing questions.",
    "variables": {
      "company": "Acme Corp",
      "topic": "billing"
    }
  },
  "requestId": "req_vwx"
}

---

Access Control

Prompts follow the platform's multi-tenant access model:

Scenario	Access
Owner	Full read/write/delete
Shared user	Read only
Public prompt (same org)	Read only
Different organization	No access
API key with prompts:read	Read access to owned/shared/public prompts
API key with prompts:write	Full CRUD on owned prompts

Error Codes

Code	Status	Description
not-authorized	401	Missing or invalid authentication
not-found	404	Prompt not found or no access
access-denied	403	Insufficient permissions (e.g., trying to edit someone else's prompt)
validation-error	400	Invalid request body (missing name, invalid type, etc.)
version-not-found	404	Specified version number does not exist