Run a published prompt
with one stable API.

Your application calls ReadPrompt by prompt name or ID. ReadPrompt validates variables, selects an eligible model-ready target, and returns output that matches your published schema.

1. 01
   Create a project and prompt

   Define variables and an output contract, then publish a version with at least one enabled READY target.

2. 02
   Create an execution API key

   Use a project-scoped key with the execute scope and store it in your server environment.

3. 03
   Install the SDK or call the API

   Use the official server-side SDK, or send a JSON variables object to the stable Executor endpoint.

4. 04
   Use validated data

   Read the prompt-specific data object and log request_id for troubleshooting.

ReadPrompt separates the application contract from the model decision. Your backend calls one prompt identity; ReadPrompt selects an eligible target and returns only schema-valid data.

A prompt name is a stable, readable application identifier such as customer-support-reply. Your application calls that name, while ReadPrompt resolves the active published version inside the project tied to the execution key.

Use the official SDKs from trusted server-side, worker, or serverless code. They provide execution results, typed errors, and SSE parsing without exposing your execution key to the browser.

npm install @readprompt/sdk

import { ReadPrompt } from "@readprompt/sdk";

const readprompt = new ReadPrompt({
  apiKey: process.env.READPROMPT_EXECUTION_API_KEY!,
});

const result = await readprompt.execute<{ summary: string }>(
  "company-brief",
  { company: "Acme" },
);

console.log(result.data.summary);
console.log(result.meta.resolved_model);

Every execution request uses a project-scoped API key. Create it after signing in, then keep it in a server-side secret store or encrypted environment variable.

Base URL: https://sdk.readprompt.dev/v1
Authorization: Bearer $READPROMPT_EXECUTION_API_KEY
Content-Type: application/json

ReadPrompt validates request variables before a model is called and validates the final response against the published output schema before it is returned to your application.

• variables must be a JSON object that exactly satisfies the prompt version variables schema.
• Required fields, types, enums, array items, and additionalProperties rules are enforced.
• The response data shape is prompt-specific. Do not assume an answer field.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["summary"],
  "properties": { "summary": { "type": "string" } }
}

{
  "request_id": "73d676d1-d929-43b6-91f1-a5f9066eb7c8",
  "data": { "summary": "Acme is ready for expansion." },
  "meta": {
    "prompt_id": "13ededb4-7e14-49b0-bc3c-729ad6e04f7b",
    "prompt_name": "Company Brief",
    "version_number": 3,
    "requested_provider": "openai",
    "requested_model": "gpt-5.4-mini",
    "resolved_model": "openai/gpt-5.4-mini",
    "fallback_used": false,
    "latency_ms": 1321
  }
}

Your application does not choose a provider or model for each call. The published prompt version defines the enabled targets, routing mode, and fallback policy. Only enabled READY targets with an optimized artifact are eligible.

Fallback may occur after an eligible target times out, fails, or returns output that does not satisfy your schema. Executor moves directly to the next candidate instead of retrying the same failing target.

• Keep API keys in a server-side secret manager.
• Create separate keys for staging, production, and background workloads.
• Validate end-user authorization before executing a prompt.
• Use application timeouts and bounded retries for transient failures.
• Log request IDs and execution metadata for traceability.