Prompts API

Create, read, update, and delete prompts.

List Prompts

GET /api/v1/prompts

Query Parameters

Parameter	Type	Description
limit	number	Max results (default: 20, max: 100)
offset	number	Pagination offset
tags	string	Comma-separated tags to filter
status	string	Filter by status (active, draft, archived)

Response

{
  "data": [
    {
      "id": "prompt_123",
      "name": "Customer Support",
      "content": "You are a helpful...",
      "llmModel": "gpt-4o",
      "description": "Main support chatbot",
      "tags": ["support", "production"],
      "status": "active",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0
  }
}

Get Prompt

GET /api/v1/prompts/:id

Response

{
  "id": "prompt_123",
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "description": "Main support chatbot",
  "tags": ["support", "production"],
  "status": "active",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

Create Prompt

POST /api/v1/prompts

Request Body

{
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "description": "Main support chatbot",
  "tags": ["support", "production"]
}

Required Fields

Field	Type	Description
name	string	Display name
content	string	Prompt content
llmModel	string	Target model (gpt-4o, claude-3-5-sonnet, etc.)

Optional Fields

Field	Type	Description
description	string	What this prompt does
tags	string[]	Organization tags
temperature	number	Model temperature (0-2)
maxTokens	number	Max response tokens

Response

{
  "id": "prompt_456",
  "name": "Customer Support",
  "content": "You are a helpful customer support agent...",
  "llmModel": "gpt-4o",
  "status": "active",
  "createdAt": "2025-01-20T14:30:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

Status: 201 Created

Update Prompt

PATCH /api/v1/prompts/:id

Request Body

{
  "content": "Updated prompt content...",
  "tags": ["support", "v2"]
}

All fields are optional. Only provided fields are updated.

Response

{
  "id": "prompt_123",
  "name": "Customer Support",
  "content": "Updated prompt content...",
  "updatedAt": "2025-01-20T15:00:00Z"
}

Delete Prompt

DELETE /api/v1/prompts/:id

Response

{
  "success": true,
  "message": "Prompt deleted"
}

Status: 200 OK

Get Prompt Status

GET /api/v1/prompts/:id/status

Get prompt details including optimization state and performance metrics.

Response

{
  "id": "prompt_123",
  "name": "Customer Support",
  "status": "active",
  "optimizationState": "idle",
  "metrics": {
    "conversationCount": 1247,
    "taskCompletionRate": 87.3,
    "avgSentiment": 0.72
  },
  "lastOptimized": "2025-01-18T10:00:00Z"
}

---

Get Prompt Insights

GET /api/v1/prompts/:id/insights

Get aggregated performance insights for a prompt based on conversation data.

Query Parameters

Parameter	Type	Default	Description
days	number	30	Number of days to look back (7, 30, 90, or all)

Response

{
  "promptId": "prompt_123",
  "period": {
    "days": 30,
    "from": "2024-12-21T00:00:00Z",
    "to": "2025-01-20T23:59:59Z"
  },
  "summary": {
    "totalConversations": 1247,
    "completedConversations": 1089,
    "abandonedConversations": 158,
    "completionRate": 87.3
  },
  "metrics": {
    "taskCompletion": {
      "rate": 82.5,
      "trend": "+3.2%"
    },
    "sentiment": {
      "average": 0.72,
      "distribution": {
        "positive": 68,
        "neutral": 24,
        "negative": 8
      }
    },
    "avgResponseTime": 1.2,
    "avgConversationLength": 6.4
  },
  "topIssues": [
    {
      "issue": "Unclear refund policy explanation",
      "frequency": 23,
      "impact": "high"
    }
  ],
  "recommendations": [
    "Consider adding specific refund timelines to reduce follow-up questions"
  ]
}

---

Error Responses

Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Prompt not found"
  }
}

Status: 404 Not Found

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "llmModel": "Must be a valid model name"
    }
  }
}

Status: 400 Bad Request