REST API

Get API Key

Overview

The PromptForge REST API lets you fetch your prompts programmatically and inject variables at request time. Use it to pull managed, versioned prompts into any backend service without redeploying your application.

Base URL
https://www.promptforge-app.com

Quick Start

Follow these steps to make your first API request.

1. Create a prompt

  1. Go to the Prompts page and click New Prompt.
  2. Give it a title and write your prompt content.
  3. Use {{variable}} placeholders for any dynamic values (e.g. {{role}}).
  4. Save. PromptForge assigns the prompt a unique ID, version 1, and automatically sets it as the stable version.

2. Find your prompt ID

Open the prompt editor. The ID appears in the URL: /dashboard/prompts/YOUR_PROMPT_ID. It is also shown in the API Usage panel on the same page, with ready-to-copy curl examples pre-filled for your variables.

3. Get an API key

Generate a key on the API settings page. Include it as a Bearer token on every request.

4. Make a request

Fetch a prompt and pass your variables as query parameters:

curl -G "https://www.promptforge-app.com/api/v1/prompts/YOUR_PROMPT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "_version=stable" \
  -d "role=developer" \
  -d "task=debug"

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Keys can be generated and revoked on the API settings page.

Required header
Authorization: Bearer YOUR_API_KEY

Keep your key secure

Never include your API key in client-side code or public repositories. Make API calls from your backend server only.

Endpoints

There is one endpoint for fetching prompts, accessible via GET or POST. Both methods return the same response.

Endpoint
GET/api/v1/prompts/:id
POST/api/v1/prompts/:id

Use GET to pass variables as query parameters. Use POST to pass them in a JSON body. Prefer POST for prompts with many variables or long values.

Path parameters
idRequired. The unique identifier of the prompt.
Version channels
stableDefault. Resolves to the last manually promoted version. Ideal for production — it never changes until you explicitly promote a new version to stable.
latestAlways resolves to the highest-numbered version. Useful for development and staging so you see every change immediately.
2Any positive integer pins the request to that exact, immutable version. Useful for A/B testing specific versions or reproducing past behaviour.
Query parameters (GET)
_versionOptional. stable (default), latest, or a specific version number such as 2.
[vars]Depends on prompt. One query parameter per variable defined in the prompt. E.g. role=developer&task=debug.
Request body (POST)
variablesRequired. An object mapping variable names to their values. E.g. {"role":"developer"}.
versionOptional. "stable" (default), "latest", or a version number. If both version and the _version query param are provided, the query param takes precedence.
GET request (variables as query params)
curl -G "https://www.promptforge-app.com/api/v1/prompts/YOUR_PROMPT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "_version=stable" \
  -d "role=developer" \
  -d "task=debug"
POST request (variables in body)
curl -X POST "https://www.promptforge-app.com/api/v1/prompts/YOUR_PROMPT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "stable",
    "variables": {
      "role": "developer",
      "task": "debug"
    }
  }'
Success response (200)
{
  "id": "abc123-def456-...",
  "version": 3,
  "channel": "stable",
  "title": "My Assistant Prompt",
  "content": "You are a developer. Help me debug...",
  "variables": ["role", "task"],
  "createdAt": "2025-01-15T10:30:00.000Z"
}

The content field contains the fully rendered prompt with all variables replaced. The channel field tells you which alias resolved the request: "stable", "latest", or "pinned".

Variables

Variables let you turn a static prompt into a reusable template. Wrap any placeholder in double curly braces: {{variable}}. When you call the API, pass the values for those placeholders and the API returns the fully rendered content.

You are a {{role}} assistant. Help me with {{task}}.

Reserved variable names

Names starting with _ are reserved for system parameters such as _version. The prompt editor will block you from saving a prompt that uses reserved names.

Missing variables return 400

If the request does not include all variables that the prompt requires, the API returns a 400 error with details about which variables are missing. This ensures your application never receives a partially rendered prompt.
400 error response (missing variables)
{
  "error": "missing_variables",
  "message": "Missing required variables",
  "required": ["role", "task", "tone"],
  "missing": ["tone"],
  "provided": ["role", "task"]
}

Error Codes

The API uses standard HTTP status codes. All error responses include a JSON body with at minimum an error and message field.

401
Unauthorized
Missing or invalid API key.
403
Forbidden
Your account does not have an active subscription.
404
Not Found
No prompt exists with that ID, or you do not own it.
400
Bad Request
One or more required variables were not provided.
422
Unprocessable
The version value is not "stable", "latest", or a positive integer.
429
Rate Limited
Your monthly request quota has been exceeded.

Rate Limiting

Each plan includes a monthly request quota. The counter resets at the start of each calendar month.

Starter10,000 requests / month
Pro100,000 requests / month
Business500,000 requests / month
Rate limit headers

Every response includes these headers so you can track consumption:

X-RateLimit-LimitYour monthly request quota.
X-RateLimit-RemainingRequests remaining this month.
X-RateLimit-ResetISO timestamp of when the quota resets.

Exceeded your quota?

The API returns a 429 status code. You can monitor your current usage and upgrade your plan on the API settings page.