REST API
Prompt workflows
Generate, analyze, optimize, refine, reverse-engineer, and estimate prompts through the REST API.
Verified against the implementation ·
Generate a prompt
POST /prompts/generate accepts a goal or instruction in message. ready_to_use fills concrete details and avoids placeholders; reusable preserves useful variables for later reuse.
| Field | Type | Rules |
|---|---|---|
| message | string | Required; 1–6,000 characters |
| mode | enum | auto, general, research, writing, planning, agent, image, video, code, automation |
| outputMode | enum | ready_to_use (default) or reusable |
| targetModel | string enum | Universal by default; use GET /models for the current list |
| language | string | 2–20 characters; en by default |
| generationId | string or null | Optional; continue existing generator history |
| currentPrompt | string or null | Optional; up to 20,000 characters |
| conversation | array | Up to 50 user/assistant messages, 4,000 characters each |
| attachmentIds | Asset ID array | Up to 5 completed temporary uploads |
Analyze and optimize
| Endpoint | Required scope | Result |
|---|---|---|
| POST /prompts/analyze | prompts:analyze | Analysis saved to optimization history |
| POST /prompts/optimize | prompts:optimize | One or two optimized versions |
| POST /prompts/analyze-and-optimize | prompts:analyze + prompts:optimize | Analysis and optimized versions in one operation |
curl -X POST https://api.promptessor.com/v1/prompts/analyze-and-optimize \
-H "Authorization: Bearer pt_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: optimize-brief-001" \
-d '{
"prompt": "Write a launch email for our app",
"context": "Audience: independent designers. Tone: confident, concise.",
"targetModel": "Claude",
"variationCount": 2,
"language": "en"
}'- prompt is required and supports up to 50,000 characters.
- context is optional and supports up to 20,000 characters.
- variationCount is 1 by default and accepts only 1 or 2.
- attachmentIds accepts up to five completed temporary asset IDs.
Refine from feedback
POST /prompts/refine refines any prompt and stores standalone refinement history. POST /optimizations/{id}/refinements appends a new refinement to an existing optimization record.
{
"prompt": "Write a landing page headline",
"feedback": "Make it more concrete and emphasize the time saved",
"targetModel": "ChatGPT",
"language": "en",
"attachmentIds": []
}Reverse Prompt
POST /reverse-prompts infers a reusable prompt from an image, sampled video frames, text, or a public URL. Reverse Prompt results do not create product history.
| type | Required input | Limits |
|---|---|---|
| image | uploadId | Asset ID of a completed reverse_image upload |
| video | frames, frameCount, videoDuration | 1–30 data:image/ frames; duration up to 600 seconds |
| text | content | 10–100,000 characters |
| url | url | Public URL up to 2,048 characters |
Visible website experience
URL reverse prompting analyzes the public, visible website experience. It does not authenticate into private pages or promise a browser-perfect reconstruction.
Estimate tokens
POST /prompts/token-estimate requires usage:read and a prompt string. It is a read-classified request and does not consume an AI workflow credit.