Prompts API

Full REST reference for the prompts domain. All routes are under /api/prompts, require a Cognito JWT (Authorization: Bearer <token>), and are backed by services/backend/lambda/prompts_handler.py / prompts_service.py. See specs/api/prompts.md in the repo for the underlying spec this page is based on, and the Prompts feature guide for product-level behavior.

Endpoints at a glance

No role-based restriction

Create

POST /api/prompts

// Request
{
  "workspace_id": "ws_123",
  "name": "Professional Thought Leader",
  "system_instruction": "You are a professional LinkedIn writer.",
  "user_template": "Write about: {idea_title}\n\n{examples}",
  "tone": "professional",
  "default_audience": "Developers",
  "default_language": "English"
}

// 201 Response
{
  "prompt_id": "a1b2c3d4-...",
  "workspace_id": "ws_123",
  "name": "Professional Thought Leader",
  "system_instruction": "You are a professional LinkedIn writer.",
  "user_template": "Write about: {idea_title}\n\n{examples}",
  "tone": "professional",
  "default_audience": "Developers",
  "default_language": "English",
  "is_default": false,
  "created_by": "user_111",
  "created_at": "2026-07-17T12:00:00+00:00",
  "updated_at": "2026-07-17T12:00:00+00:00"
}

workspace_id, name, system_instruction, and user_template are required (400 if missing or empty after trimming). tone must be one of professional, casual, provocative, educational, storytelling (400 otherwise, error message lists the valid set alphabetically).

List

GET /api/prompts?workspaceId=ws_123

// 200 Response
{ "items": [ /* prompt objects, same shape as Create's response */ ], "count": 2 }

Get

GET /api/prompts/{id}?workspaceId=ws_123

Unlike List, this is not restricted to prompts you created — any workspace member can fetch any prompt in the workspace by id.

Returns the prompt object (same shape as Create's response).

Update

PUT /api/prompts/{id}

Partial update — send only the fields you want to change, plus workspace_id (required for the membership check).

// Request — rename and switch tone
{ "workspace_id": "ws_123", "name": "Punchy Thought Leader", "tone": "provocative" }

updated_at is always refreshed, even on an otherwise-empty body. Omitting a field leaves it unchanged (there's no way to clear text fields except by sending an explicit empty value).

Delete

DELETE /api/prompts/{id}?workspaceId=ws_123

Creator-only, same rule as Update.

// 200 Response
{ "deleted": true }

Note this endpoint returns 200, not 204 — the body is not empty.

Set default

PUT /api/prompts/{id}/default

Creator-only, same rule as Update. Sets is_default: true on this prompt and is_default: false on any other prompt you created in the same workspace.

// Request
{ "workspace_id": "ws_123" }

// 200 Response — is_default now true, updated_at refreshed
{ "prompt_id": "a1b2c3d4-...", "is_default": true, "...": "..." }