Developers

Prompts API

Create, update, invoke, and inject prompts over HTTP

API base URL

https://api.promptcache.app

Authenticated prompt endpoints live under /api/v1/prompts. Send Authorization: Bearer … with an API key or user access token.

With an API key, the server resolves your workspace from the key. With a user JWT, include organizationId in the query string or body where noted below.

For Node.js and browser apps, prefer the official @optiqlabs/promptcache-sdk package, see the JavaScript / TypeScript SDK page.

Permissions at a glance

Action	API key	User JWT
List / get / create / update / delete prompts	Yes (with scopes)	Yes
Invoke / inject	Yes	Yes
Publish / unpublish	No	Yes
Fork (version or public)	No	Yes

List prompts

With an API key

The organization is inferred from the key; query parameters are optional besides pagination and filters.

Code

GET /api/v1/prompts?page=1&limit=20&search=&tags=

With a user JWT

Include the org in the query string:

Code

GET /api/v1/prompts?organizationId=YOUR_ORG_ID&page=1&limit=20&search=&tags=

Response (HTTP JSON uses the standard success envelope)

Code

{
  "data": {
    "prompts": [{ "_id": "…", "name": "My Prompt", "slug": "my-prompt" }],
    "pagination": { "page": 1, "limit": 20, "total": 5, "pages": 1 }
  }
}

The SDK returns the inner payload: prompts.list() → IPrompt[], prompts.listPaginated() → { prompts, pagination }.

Use search for text filtering and tags (comma-separated or as your client sends) to narrow collections. Pagination is page/limit based.

Variable names are inferred from the template using {{variable_name}} syntax (letters, numbers, underscores). You may supply an initial variables array to override types and descriptions; otherwise the server derives minimal definitions.

With an API key, omit organizationId, the prompt is created in the key’s organization.

Code

POST /api/v1/prompts
Content-Type: application/json
 
{
  "name": "Email Responder",
  "description": "Drafts a professional reply to a customer email",
  "template": "# Reply to {{customer_name}}\n\nDear {{customer_name}},\n\nThank you for reaching out about **{{topic}}**…",
  "tags": ["email", "support"],
  "isPublic": false
}

With a user JWT, include organizationId when it is not supplied as ?organizationId= on the same request pattern your client uses for auth context:

Code

{
  "organizationId": "<orgId>",
  "name": "Email Responder",
  "description": "Drafts a professional reply to a customer email",
  "template": "# Reply to {{customer_name}}\n\nDear {{customer_name}},",
  "tags": ["email", "support"],
  "isPublic": false
}

The response includes a slug (stable, URL-safe) derived from the name. If the name collides, the backend generates a unique slug.

Save, update the draft only

Code

PUT /api/v1/prompts/:id
Content-Type: application/json
 
{
  "template": "Updated template with {{new_var}}",
  "variables": [
    { "name": "new_var", "type": "string", "required": true, "description": "The new variable" }
  ]
}

Saving updates the Prompt document (template, variables, metadata). It does not create a PromptVersion. Version history is created only on publish.

If you remove placeholders from the template, the response may include staleVariables, names that used to exist but no longer appear in {{…}}, so you can clean up variable metadata in a follow-up request.

Publish

Code

POST /api/v1/prompts/:id/publish

Creates a new published PromptVersion from the current draft. Requires a user JWT (see Authentication). Semantics: Versions.

Unpublish (public catalog)

Code

DELETE /api/v1/prompts/:id/publish

Clears public visibility for this prompt. Published version rows remain for history.

Invoke

Code

POST /api/v1/prompts/:id/invoke
Content-Type: application/json
 
{
  "variables": {
    "customer_name": "Alice",
    "topic": "billing issue"
  }
}

Invoke renders the live draft on the prompt document using the variable map you provide. Required variables (per metadata) must be present or the API returns 400 listing missing names. Default values from variable definitions are applied when a key is omitted.

Response

Code

{
  "promptId": "…",
  "promptName": "Email Responder",
  "variables": { "customer_name": "Alice", "topic": "billing issue" },
  "renderedContent": "…",
  "invokedAt": "2026-04-08T10:00:00.000Z"
}

Use invoke for production calls where you want the current saved template (after CI or dashboard saves).

Inject (preview)

Code

POST /api/v1/prompts/:id/inject
Content-Type: application/json
 
{ "variables": { "customer_name": "Bob" } }

Inject also renders the live draft but is oriented toward preview: it returns unresolvedVariables for {{…}} names still missing from the payload after defaults, so UIs can highlight incomplete test data. Behavior matches invoke for merging defaults and rendering.

Variables

Field	Type	Description
`name`	string	Matches `{{name}}` in the template
`type`	enum	`string`, `number`, `boolean`, `array`, `object`
`required`	boolean	Must be supplied on invoke (unless defaulted)
`defaultValue`	any	Used when the caller omits the key
`description`	string	Human hint for authors and API consumers

Patch a single variable’s metadata:

Code

PUT /api/v1/prompts/:id/variables/:variableName
Content-Type: application/json
 
{ "type": "number", "required": true, "description": "Customer ID" }

Delete a prompt

Code

DELETE /api/v1/prompts/:id

Deletes the prompt and its associated PromptVersion rows and public index entries. Irreversible.

Operational patterns

Edit in dashboard or via API with PUT until the draft is ready; run inject from tooling to validate rendering.
Publish from an authenticated user session to freeze a snapshot for compliance or rollback.
Invoke from integrations using an API key with prompts:read for execution-only workloads.
Fork a published version when branching work into another team or organization without overwriting the original.

For published history and fork rules, see Versions. For unauthenticated read/invoke on shared prompts, see Public API.