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. New extension keys default to items:read; direct API callers can omit expiresInDaysto keep the previous no-expiry behavior, while the UI preselects one year and still keeps Never as an explicit choice.

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

Anonymous reads of the public item list, public item detail, and approved public downloads return wildcard CORS with no credentials and no-store. This lets offline-file and self-hosted Prompt Organizer copies read the public catalogue.

Credentialed and mutating endpoints remain origin-scoped to:

• https://promptorganizer.app
• https://www.promptorganizer.app
• Exact configured Chrome extension origins only

Extension access fails closed until the deployment is configured with the exact published extension ID. Unknown extension origins receive no Access-Control-Allow-Origin header for credentialed or mutating requests, and those responses vary on Origin.

GET /api/v1/items

List approved public items. Mirrors the browse page filters and returns the full canonical item shape by default; pass view=summary to omit prompt bodies, system prompts, and structured package payloads for browse cards. Fetch /api/v1/items/:id for a single record.

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.

The :id segment accepts the raw row UUID, the stored source_app_id, or the derived p_{uuidWithoutDashes} list id.

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

Download a single item as a JSON file (application/json, filename prompt-{id}.json). A successful response records one download in both lifetime popularity and the weekly digest activity rollup.

The same :id forms apply here, and anonymous downloads of approved public items are cache-busted withno-store. Those public downloads are simple GETs with no Authorization header, so they do not rely on a preflight; credentialed downloads still use the allowlisted origin gate.

GET /api/v1/me/items

List all items belonging to the authenticated user, including private ones. Requires items:read on the bearer key.

Optional pagination: pass ?limit= (1-100) and ?offset= to page through large libraries; the response then includes total, limit, and offset alongside items. Without limit, all items are returned (legacy behavior).

POST /api/v1/me/items

Create a new item via a key with items:write. Items created this way default to private visibility and are automatically scanned.

submittedBy is an attribution preference, not a free-form author name. Omit it or send anonymous for no public attribution. Any other value requests attribution, and the server substitutes the authenticated owner's verified profile handle; caller-supplied names are never persisted.

Request body

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

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.