Start building

Executor API

One endpoint contract.
Every configured model.

Use the Executor API from a trusted backend to run the active published version of a prompt by readable name or immutable ID.

POST/v1/prompt-names/{prompt_slug}/execute

Bearer key -> schema-validated data

Browse API reference

Overview

Base URL: https://sdk.readprompt.dev/v1. All calls are server-to-server and require a project-scoped execution API key.

Required headers

text

Authorization: Bearer <READPROMPT_EXECUTION_API_KEY>
Content-Type: application/json

Request envelope

json

{
  "variables": {
    "company": "Acme"
  }
}

The variables object must exactly satisfy the active prompt version’s variables schema. The returned data object always satisfies that version’s output schema.

Successful response

json

{
  "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
  }
}

Execute by prompt name

Use the stable, URL-safe prompt slug when your application benefits from readable configuration. The slug is resolved only within the project associated with the execution key.

Endpoint

http

POST /v1/prompt-names/{prompt_slug}/execute

Request body

json

{
  "variables": {
    "company": "Acme"
  }
}

curl: execute by prompt name

bash

curl --request POST "https://sdk.readprompt.dev/v1/prompt-names/company-brief/execute" \
  --header "Authorization: Bearer ${READPROMPT_EXECUTION_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "variables": { "company": "Acme" }
  }'

Execute by prompt ID

Use a prompt ID when your integration already stores an immutable ReadPrompt UUID. Like names, IDs resolve only inside the project attached to the execution key.

Endpoint

http

POST /v1/prompts/{prompt_id}/execute

Request body

json

{
  "variables": {
    "company": "Acme"
  }
}

curl: execute by prompt ID

bash

curl --request POST "https://sdk.readprompt.dev/v1/prompts/00000000-0000-0000-0000-000000000000/execute" \
  --header "Authorization: Bearer ${READPROMPT_EXECUTION_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{ "variables": { "company": "Acme" } }'

Stream a prompt

Use Server-Sent Events when your application needs progressive display. Normal execution is simpler when you only need the final validated result.

By prompt name

http

POST /v1/prompt-names/{prompt_slug}/execute/stream

By prompt ID

http

POST /v1/prompts/{prompt_id}/execute/stream

curl: stream by prompt name

bash

curl --no-buffer --request POST "https://sdk.readprompt.dev/v1/prompt-names/company-brief/execute/stream" \
  --header "Authorization: Bearer ${READPROMPT_EXECUTION_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{ "variables": { "company": "Acme" } }'

SSE events

text

event: delta
data: {"request_id":"...","text":"partial model output"}

event: complete
data: {"request_id":"...","data":{"summary":"Validated result"},"meta":{"fallback_used":false,"latency_ms":1321}}

event: error
data: {"request_id":"...","code":"stream_interrupted","message":"The stream stopped before it completed."}

  • delta.text is partial display content only and may be incomplete JSON.
  • complete.data is terminal and validates against the active output schema.
  • error is terminal when a failure occurs after streaming begins.

Errors and recovery

StatusMeaningRecovery
401Missing, invalid, expired, or revoked keyCheck the Bearer header or rotate the project key
403Key lacks scope or belongs to another projectUse an execute key from the prompt project
404Prompt name or ID was not foundConfirm the prompt identity in the key project
409No active version or eligible READY targetPublish after target optimization completes
422Variables do not satisfy the schemaCorrect required fields, types, values, or extra properties
429Organization or API-key rate limit reachedRespect Retry-After and reduce request rate
502 / 504Eligible targets failed or timed outUse a bounded retry only when repeating the work is safe

Persist request_id, fallback_used, and latency_ms in your own application logs. Include the request ID when you need support.