Documentation

REST API Reference

Promptmark exposes ~31 JSON API endpoints under /api/. All endpoints require authentication via Bearer JWT in the Authorization header.

Authorization: Bearer YOUR_JWT_TOKEN

Prompts

POST /api/prompts
Auth: Bearer JWT

Create a new prompt.

Body:

{
  "title": "My Prompt",
  "prompt": "Write a {{style}} email about {{topic}}",
  "notes": "Optional notes",
  "type_id": "general",
  "tags": ["email", "writing"],
  "collection_id": "col_123",
  "is_public": false,
  "is_remixable": false,
  "self_rating": 3.5
}

Response: 201 Created with the created prompt object.

GET /api/prompts
Auth: Bearer JWT

List prompts with optional filtering.

Query parameters: search, tag, collection_id, type_id, page, limit

Response: 200 OK with paginated prompt list.

GET /api/prompts/:id
Auth: Bearer JWT

Get a specific prompt by ID.

Response: 200 OK with the prompt object.

PUT /api/prompts/:id
Auth: Bearer JWT

Update a prompt. Only provided fields are changed.

Response: 200 OK with the updated prompt.

DELETE /api/prompts/:id
Auth: Bearer JWT

Soft-delete a prompt.

Response: 204 No Content

Tags

POST /api/tags/add
Auth: Bearer JWT

Add a tag to a prompt.

Body: {"prompt_id": "...", "tag": "new-tag"}

POST /api/tags/remove
Auth: Bearer JWT

Remove a tag from a prompt.

Body: {"prompt_id": "...", "tag": "old-tag"}

POST /api/tags/rename
Auth: Bearer JWT

Rename a tag across all prompts.

Body: {"old_name": "old-tag", "new_name": "new-tag"}

Versions

GET /api/prompts/:id/versions
Auth: Bearer JWT

List version history for a prompt.

Response: 200 OK with array of version snapshots.

GET /api/prompts/:id/versions/:vid
Auth: Bearer JWT

Get a specific version snapshot.

Response: 200 OK with the version object.

POST /api/prompts/:id/versions
Auth: Bearer JWT

Create an explicit major version with a description.

Body: {"description": "Version description"}

POST /api/prompts/:id/restore/:vid
Auth: Bearer JWT

Restore a prompt to a previous version. Snapshots current state first.

Response: 200 OK with the restored prompt.

Collections

GET /api/collections
Auth: Bearer JWT

List all collections.

Response: 200 OK with collection array.

POST /api/collections
Auth: Bearer JWT

Create a new collection.

Body: {"name": "...", "description": "...", "color": "cyan", "icon": "code"}

GET /api/collections/:id
Auth: Bearer JWT
Get a specific collection.
PUT /api/collections/:id
Auth: Bearer JWT
Update a collection.
DELETE /api/collections/:id
Auth: Bearer JWT
Delete a collection. Prompts become uncategorized.
PUT /api/prompts/:id/collection
Auth: Bearer JWT

Move a prompt to a collection.

Body: {"collection_id": "col_123"}

Testing

POST /api/test/start
Auth: Bearer JWT

Start a test run. Returns a test ID for SSE streaming.

Body: {"prompt_id": "...", "model_id": "...", "variables": {...}}

GET /api/test/stream
Auth: Bearer JWT

SSE stream for test responses.

Query: id (test ID from start endpoint)

POST /api/test/:id/feedback
Auth: Bearer JWT

Submit feedback for a test response.

Body: {"rating": 1, "notes": "Great response"}

Achievements

GET /api/onboarding/achievements
Auth: Bearer JWT
Get achievement states for the current user.
DELETE /api/onboarding/dismiss
Auth: Bearer JWT
Dismiss the onboarding widget from the dashboard.
POST /api/onboarding/restore
Auth: Bearer JWT
Restore the onboarding widget.

Scans

POST /api/prompts/:id/scan/acknowledge
Auth: Bearer JWT

Acknowledge a safety scan issue.

Body: {"category": "pii"}

Categories: pii, injection, secrets, danger

Sharing

GET /api/share/prompt/:id
Auth: None (public)
Get shareable content for a public prompt.
GET /api/share/collection/:id
Auth: None (public)
Get shareable content for a public collection.
GET /api/share/prompt/:id/qr
Auth: None (public, rate-limited)
Generate a QR code image for a public prompt.

Utility

GET /api/ping
Auth: Bearer JWT

Check authentication status. Returns 200 if token is valid, 401 if not.

Response: {"status": "ok", "user_id": "123"}

GET /health
Auth: None
Health check endpoint. Returns system status.