Integration API & Prompt Execution

The Power Prompt public REST API allows organisations to seamlessly integrate enterprise prompt templates into external business systems, including ERPs, CRMs, custom scripts, and backend automations.

All API communications require HTTPS, and payload exchanges follow standard JSON conventions.

1. Authentication & Security

Access to the public API is governed through a Team API Key generated by a team manager or administrator via the dashboard (Team Management > Integrations & API Keys).

Mandatory Header

Every request to the API must include your key in the following HTTP request header:

X-API-Key: pp_live_your_secure_api_key_here

[!IMPORTANT] API Key Security Guidelines:

Never expose API keys in client-side code, public browser scripts, or mobile client binaries.

Store keys strictly in server-side secret managers or environment vaults.

Each key is scoped exclusively to the workspaces and prompt catalogues assigned to its governing team.

2. Executing a Prompt Template

This endpoint executes an approved prompt template, dynamically substituting variables before dispatching the payload to the configured AI model.

Request

Method: POST
Path: /api/v1/prompts/execute
Headers:
- Content-Type: application/json
- X-API-Key: pp_live_...

Request Body (JSON)

{
  "prompt_id": "pr_8f4d92a1-3b7c-4e8a-9f12-0a1b2c3d4e5f",
  "variables": {
    "client_name": "Acme Corporation",
    "document_type": "Service Level Agreement",
    "notes": "Annual renewal with indexed cost adjustment."
  },
  "options": {
    "temperature": 0.2
  }
}

Parameters

Field	Type	Required	Description
`prompt_id`	String (UUID)	Yes	Unique identifier of the target prompt to execute.
`variables`	Key/Value Object	Yes	Values for dynamic placeholders (`{{variable_name}}`) defined in the prompt.
`options.temperature`	Number (0.0 to 1.0)	No	Sampling temperature (optional; defaults to the prompt template’s configured setting).

Response

Success (`200 OK`)

{
  "success": true,
  "execution_id": "exec_5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
  "prompt_id": "pr_8f4d92a1-3b7c-4e8a-9f12-0a1b2c3d4e5f",
  "version": 3,
  "result": "Final generated text output returned from the AI model...",
  "usage": {
    "total_tokens": 420
  },
  "created_at": "2026-09-27T10:30:00Z"
}

3. Error Handling (RFC 7807 Standard)

When a request cannot be fulfilled, the API returns an appropriate HTTP status code along with a standardised error payload adhering to the RFC 7807 (Problem Details for HTTP APIs) specification.

{
  "type": "https://doc.powerprompt.eu/errors/missing-variable",
  "title": "Missing Required Variable",
  "status": 400,
  "detail": "Required variable {{client_name}} was not provided in the request payload.",
  "instance": "/api/v1/prompts/execute"
}

Common HTTP Error Codes

Status Code	Meaning	Common Cause
`400 Bad Request`	Malformed Request	Invalid JSON structure or missing mandatory prompt variables.
`401 Unauthorized`	Authentication Failed	Missing or invalid `X-API-Key` header.
`403 Forbidden`	Access Denied	The API key lacks permissions to execute this prompt or access the parent workspace.
`404 Not Found`	Resource Not Found	Specified `prompt_id` does not exist or has been archived.
`429 Too Many Requests`	Rate Limit Exceeded	Exceeded allowed requests per minute for this API key.
`502 / 504 Gateway Error`	AI Provider Error	Upstream AI provider timeout or service degradation.

4. Rate Limiting & Integration Best Practices

Default Call Quotas: Standard API keys have a default ceiling of 60 requests per minute. For high-volume enterprise ingestion, contact your organisation administrator.
Retry Mechanism: When receiving transient errors (429 or 503), implement exponential backoff with random jitter.
Pre-Flight Validation: Verify that all required template variables are populated within your application before dispatching requests to the API.