Skip to content

API Reference

Base URL: http://localhost:5000 (pip) or http://localhost:5002 (Docker)

Endpoints

List Prompts

GET /api/prompts
Returns all prompts with metadata (title, category, tags, sections count, size, modified date).

curl http://localhost:5002/api/prompts

Get Prompt Details

GET /api/prompts/<path>
Returns full content: raw markdown, parsed sections, tags, description.

curl http://localhost:5002/api/prompts/coding/code-review.md

Create Prompt

POST /api/prompts
Content-Type: application/json

curl -X POST http://localhost:5002/api/prompts \
  -H "Content-Type: application/json" \
  -d '{
    "category": "coding",
    "filename": "my-prompt",
    "title": "My Prompt",
    "sections": [{"title": "Section 1", "prompt": "Your prompt text here"}],
    "tags": ["python", "debugging"]
  }'

Required fields: category, filename, title, sections Optional fields: tags

Update Prompt

PUT /api/prompts/<path>
Content-Type: application/json

curl -X PUT http://localhost:5002/api/prompts/coding/my-prompt.md \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "sections": [{"title": "Section 1", "prompt": "Updated text"}],
    "tags": ["python"]
  }'

Required fields: title, sections Optional fields: tags (omit to preserve existing tags)

Delete Prompt

DELETE /api/prompts/<path>

curl -X DELETE http://localhost:5002/api/prompts/coding/my-prompt.md

# Also remove empty category folder
curl -X DELETE "http://localhost:5002/api/prompts/coding/my-prompt.md?delete_empty_category=true"

Download Prompt

GET /api/prompts/<path>/download
Downloads the raw .md file.

curl -O http://localhost:5002/api/prompts/coding/code-review.md/download

Import Prompt

POST /api/prompts/import
Content-Type: multipart/form-data

curl -X POST http://localhost:5002/api/prompts/import \
  -F "file=@my-prompt.md" \
  -F "category=coding"

Validation: .md extension required, max 1MB, no overwrites (409 if exists).

List Categories

GET /api/categories

curl http://localhost:5002/api/categories

List Tags

GET /api/tags
Returns all unique tags with counts.

curl http://localhost:5002/api/tags

GET /api/search?q=<query>

curl "http://localhost:5002/api/search?q=debug"

# Case-sensitive search
curl "http://localhost:5002/api/search?q=Debug&case_sensitive=true"

Health Check

GET /health

curl http://localhost:5002/health

Returns: status, version, prompts directory path, timestamp.