API Reference

Authentication

Public endpoints (browsing approved items) require no authentication. Personal endpoints require an API key via HTTP header:

Authorization: Bearer pol_your_api_key_here

Generate API keys from your Account page. Keys start with pol_ and are shown only once.

Rate limits

Authenticated (API key): 120 requests per hour per key.
Anonymous: 120 requests per hour per IP.

When a limit is exceeded, the API returns 429 Too Many Requests.

CORS

All API endpoints include CORS headers allowing requests from:

• https://promptorganizer.app
• https://www.promptorganizer.app
• Any Chrome extension origin (chrome-extension://)

GET /api/v1/items

List approved public items. Mirrors the browse page filters.

Query parameters

Response

{
  "items": [
    {
      "id": "p_...",
      "kind": "prompt",
      "type": "prompt",
      "title": "...",
      "description": "...",
      "body": "...",
      "systemPrompt": "",
      "tags": ["..."],
      "favorite": false,
      "createdAt": 1234567890000,
      "updatedAt": 1234567890000,
      "libraryId": "uuid",
      "libraryVersion": 1,
      "source": "library.promptorganizer.app"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 24
}

GET /api/v1/items/:id

Retrieve a single item. Public and approved items are readable without auth. Private items require a valid API key belonging to the owner.

GET /api/v1/items/:id/download

Download a single item as a JSON file (application/json, filename prompt-{id}.json). Also increments the download counter.

GET /api/v1/me/items

List all items belonging to the authenticated user, including private ones. Requires Authorization: Bearer pol_....

POST /api/v1/me/items

Create a new item via API key. Items created this way default to private visibility and are automatically scanned.

Request body

{
  "kind": "prompt",
  "title": "My prompt",
  "description": "What it does",
  "body": "The prompt text",
  "systemPrompt": "",
  "tags": ["tag1", "tag2"],
  "visibility": "private"
}

POST /api/v1/items/versions

Check whether any of your locally stored library prompts have been updated. No authentication required. Rate limit: 60 requests/hour per IP.

Request body

POST /api/v1/items/versions
Content-Type: application/json

{
  "items": [
    { "libraryId": "uuid", "libraryVersion": 1 },
    { "libraryId": "uuid2", "libraryVersion": 3 }
  ]
}

Maximum 200 items per request.

Response

{
  "updates": [
    {
      "libraryId": "uuid",
      "currentVersion": 2,
      "slug": "my-prompt-slug",
      "title": "My Prompt"
    }
  ]
}

Only items where the library's current_version is greater than your supplied libraryVersion are returned. An empty updates array means everything is up to date.

GET /api/v1/collections/:slug/download

Download all approved public prompts in a collection as a JSON pack file. No authentication required.

Response

Content-Disposition: attachment; filename="<slug>-pack.json"

{
  "collection": {
    "slug": "marketing-starter-pack",
    "title": "Marketing Starter Pack",
    "description": "...",
    "exportedAt": "2026-06-11T14:00:00.000Z"
  },
  "prompts": [ /* canonical item shapes */ ]
}

Canonical JSON shape

All endpoints return the app-compatible canonical shape. This is the same format accepted by the Prompt Organizer import pipeline — you can use the Open in Prompt Organizerbutton on any item page for one-click import, or POST the JSON to the app's #import= hash parameter.