REST API

v2 · current

Read, write and publish prompts over HTTP with a project API key. The read path is one GET that returns the assembled text, sections, tools, variables and the version you are running. Using v1? It keeps working; see API versions.

Base URL

All API requests should be made to:

https://superprompts.app/api/v2

Authentication

All requests require authentication using your project's API key in the request headers:

x-api-key: <YOUR_API_KEY>

Getting Your API Key: Navigate to your project settings in the dashboard to view your API key.

Endpoints

Method	Path	Purpose
GET	/api/v2/prompts	List prompts in the project
GET	/api/v2/prompts/:id	Fetch a prompt (production by default)
POST	/api/v2/prompts	Create a prompt
PUT	/api/v2/prompts/:id	Save a new version
POST	/api/v2/prompts/:id/publish	Point production at a version

Every response is { "success": true, "data": … } or { "success": false, "error": "…" }. Free projects are limited to 60 requests per minute per organization; a 429 carries X-RateLimit-* headers.

Get a prompt

Returns the assembled prompt text plus everything you need to make the model call.

Request

curl https://superprompts.app/api/v2/prompts/<PROMPT_ID> \
  -H "x-api-key: <API_KEY>"

Query param	Values
version	`production` (default), `latest` for the newest saved version, or a version hash / unique 7+ character prefix
guard	`true` (default) appends Prompt Guard anti-injection instructions; `false` returns exactly what you wrote

Response

{
  "success": true,
  "data": {
    "id": "e0a6c9d2-72e8-447e-a207-7e7f3a19be49",
    "name": "Support agent",
    "description": "Tier-1 support",
    "prompt": "<role>You help {{ customer }} with {{ topic }}.</role>\n\n<rules>1. Never promise refunds.</rules>",
    "sections": [
      { "id": "role", "title": "Role", "content": "You help {{ customer }} with {{ topic }}." },
      { "id": "rules", "title": "Rules", "content": "1. Never promise refunds." }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Find an order by id",
          "parameters": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }
        }
      }
    ],
    "variables": ["customer", "topic"],
    "version": "8481c559defedd0417ed86139fd2fbe5d4e83b72e967478eb162246248ffc9d8",
    "label": "production",
    "production_version": "8481c559defedd0417ed86139fd2fbe5d4e83b72e967478eb162246248ffc9d8",
    "created_at": "2026-02-06T23:05:36.707Z",
    "updated_at": "2026-08-23T06:59:15.619Z"
  }
}

Response fields

prompt

Enabled sections assembled in order, each wrapped in an XML-style tag named after its title. Use it as the system message.

sections

The same content split up, for teams that want to assemble it differently.

variables

Every {{ name }} referenced by the enabled sections. Compile them yourself or let an SDK do it.

tools

Function-calling tools in the OpenAI tools format. Omitted when the prompt defines none.

version

SHA-256 of the content that was served. Log it next to model outputs so you can trace a regression to a version.

label

Which pointer resolved the request: production, latest or version.

production_version

The hash currently published, or null if nothing has been published yet (the latest version is served in that case).

List prompts

curl https://superprompts.app/api/v2/prompts -H "x-api-key: <API_KEY>"

{
  "success": true,
  "data": {
    "project": { "id": "…", "name": "Support bot" },
    "prompts": [
      { "id": "…", "name": "Support agent", "description": "…",
        "production_version": "8481c55…", "latest_version": "1c4d27b…",
        "created_at": "…", "updated_at": "…" }
    ]
  }
}

Create a prompt

Provide the content as sections (an array of { title, content }) or as markdown, where every # Heading starts a section. publish: true makes the first version production immediately. Plan limits apply (5 prompts per project on Free).

curl -X POST https://superprompts.app/api/v2/prompts \
  -H "x-api-key: <API_KEY>" -H "content-type: application/json" \
  -d '{
    "name": "Support agent",
    "description": "Tier-1 support",
    "markdown": "# Role\nYou help {{ customer }}.\n\n# Rules\n1. Never promise refunds.",
    "publish": true
  }'

{ "success": true, "data": { "id": "…", "name": "Support agent", "version": "7421b10…", "published": true, "created_at": "…" } }

Save a new version

Send the full content; sections you leave out are removed from the new version. Versions are content-addressed, so saving identical content returns the existing hash with created: false.

curl -X PUT https://superprompts.app/api/v2/prompts/<PROMPT_ID> \
  -H "x-api-key: <API_KEY>" -H "content-type: application/json" \
  -d '{
    "sections": [
      { "title": "Role", "content": "You help {{ customer }} with {{ topic }}." },
      { "title": "Rules", "content": "1. Escalate refund requests." }
    ],
    "message": "escalate refunds instead of refusing",
    "publish": false
  }'

{ "success": true, "data": { "id": "…", "version": "8481c55…", "created": true, "published": false } }

Publish

Point production at a version. version is a hash, a unique prefix, or latest (the default). Rolling back is publishing an older hash. Caches are invalidated immediately.

curl -X POST https://superprompts.app/api/v2/prompts/<PROMPT_ID>/publish \
  -H "x-api-key: <API_KEY>" -H "content-type: application/json" \
  -d '{ "version": "18bab0e" }'

{ "success": true, "data": { "id": "…", "version": "18bab0e…", "published": true } }

Errors

400

Invalid body or query. The message names the field.

401

Missing or invalid API key.

403

Plan limit reached (for example the 5-prompt Free limit).

404

Prompt or version not found in this project.

429

Rate limit exceeded. Retry after X-RateLimit-Reset seconds.

500

Something failed on our side. Retry with backoff.

{ "success": false, "error": "Invalid API key" }

Next Steps

Authentication

Learn more about API key authentication

Examples

See code examples in different languages

View examples