REST API · v1.0.0

API reference

All public endpoints from the production API contract. The base URL is https://api.promptessor.com/v1.

Endpoints

45 operations in the current contract.

Download OpenAPI JSON

get/Get API information

No OAuth scope is required beyond valid authentication, or this is a public service endpoint.

Responses

200 API information

get/healthCheck API and database availability

No OAuth scope is required beyond valid authentication, or this is a public service endpoint.

Responses

200 Service is available503 Service is unavailable

get/capabilitiesGet capabilities, granted scopes, and limits

No OAuth scope is required beyond valid authentication, or this is a public service endpoint.

Responses

200 Success400 401 403 429 500

get/modelsList supported target models

No OAuth scope is required beyond valid authentication, or this is a public service endpoint.

Responses

200 Success400 401 403 429 500

get/usageGet unified product usage

Required OAuth scopes

usage:read

Responses

200 Success400 401 403 429 500

post/prompts/generateGenerate a prompt

Required OAuth scopes

prompts:generate

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
message	string	Yes	length: 1–6000
mode	string	No	allowed: auto, general, research, writing, planning, agent, image, video, code, automation; default: auto
outputMode	string	No	allowed: ready_to_use, reusable; default: ready_to_use
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
language	string	No	default: en; length: 2–20
generationId	string \| null	No	length: 1–120
currentPrompt	string \| null	No	length: 0–20000
conversation	array<object>	No	default: ; items: 0–50
conversation[].role	string	Yes	allowed: user, assistant
conversation[].content	string	Yes	length: 0–4000
attachmentIds	array<string>	No	default: ; items: 0–5

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/prompts/analyzeAnalyze a prompt

Required OAuth scopes

prompts:analyze

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
promptId	string \| null	No	—
prompt	string	Yes	length: 1–50000
language	string	No	default: en; length: 2–20
context	string	No	default: ; length: 0–20000
attachmentIds	array<string>	No	default: ; items: 0–5
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
variationCount	integer	No	allowed: 1, 2; default: 1

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/prompts/optimizeOptimize a prompt

Required OAuth scopes

prompts:optimize

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
promptId	string \| null	No	—
prompt	string	Yes	length: 1–50000
language	string	No	default: en; length: 2–20
context	string	No	default: ; length: 0–20000
attachmentIds	array<string>	No	default: ; items: 0–5
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
variationCount	integer	No	allowed: 1, 2; default: 1

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/prompts/analyze-and-optimizeAnalyze and optimize a prompt

Required OAuth scopes

prompts:analyzeprompts:optimize

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
promptId	string \| null	No	—
prompt	string	Yes	length: 1–50000
language	string	No	default: en; length: 2–20
context	string	No	default: ; length: 0–20000
attachmentIds	array<string>	No	default: ; items: 0–5
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
variationCount	integer	No	allowed: 1, 2; default: 1

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/prompts/refineRefine a prompt from feedback

Required OAuth scopes

prompts:refine

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
prompt	string	Yes	length: 1–50000
feedback	string	Yes	length: 1–10000
refinementId	string	No	—
language	string	No	default: en; length: 2–20
attachmentIds	array<string>	No	default: ; items: 0–5
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/optimizations/{id}/refinementsRefine an optimized version

Required OAuth scopes

prompts:refine

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255

JSON request body

Field	Type	Required	Rules
sourceVersionId	string	Yes	length: 1–unlimited
parentRefinementId	string	No	length: 1–unlimited
feedback	string	Yes	length: 1–10000
language	string	No	default: en; length: 2–20
attachmentIds	array<string>	No	default: ; items: 0–5
targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video

Responses

200 AI operation completed400 401 403 409 429 500 503

post/reverse-promptsReverse engineer a prompt; no history is stored

Required OAuth scopes

prompts:reverse

Parameters

Name	Location	Type	Required	Rules
Idempotency-Key	header	string	Yes	A unique key retained for 24 hours. Reuse the same key and request body when retrying.; length: 1–255
Prefer	header	string	No	Use respond-async to defer a supported AI operation.; allowed: respond-async

JSON request body

Field	Type	Required	Rules
image.type	string	Yes	value: image
image.uploadId	string	Yes	length: 1–191
image.language	string	No	default: en; length: 2–20
image.targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
video.type	string	Yes	value: video
video.frames	array<string>	Yes	items: 1–30
video.frameCount	integer	Yes	range: 1–30
video.videoDuration	number	Yes	range: unlimited–600
video.language	string	No	default: en; length: 2–20
video.targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
text.type	string	Yes	value: text
text.content	string	Yes	length: 10–100000
text.language	string	No	default: en; length: 2–20
text.targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal
url.type	string	Yes	value: url
url.url	string	Yes	format: uri; length: 0–2048
url.language	string	No	default: en; length: 2–20
url.targetModel	string	No	allowed: Universal, ChatGPT, Claude, Gemini, Grok, Llama, Mistral, DeepSeek, Perplexity, Cohere, Kimi, Qwen, GPT Image, Midjourney, Nano Banana, FLUX, Ideogram, Stable Diffusion, Lumina, Runway Image, Kling Image, Wan Image, Seedream, Veo, Runway, Kling, Seedance, Wan, MiniMax, Luma, Pika, Vidu, PixVerse, LTX, Adobe Firefly Video, Midjourney Video, Grok Imagine Video; default: Universal

Responses

200 AI operation completed202 Accepted for asynchronous processing400 401 403 409 429 500 503

post/prompts/token-estimateEstimate prompt tokens

Required OAuth scopes

usage:read

JSON request body

Field	Type	Required	Rules
prompt	string	Yes	length: 0–200000

Responses

200 Success400 401 403 429 500

get/prompt-presetsList owned prompt variable presets

Required OAuth scopes

prompts:presets:read

Parameters

Name	Location	Type	Required	Rules
search	query	string	No	length: 0–200
limit	query	integer	No	default: 25; range: 1–100
offset	query	integer	No	default: 0; range: 0–unlimited

Responses

200 Success400 401 403 429 500

post/prompt-presetsCreate a prompt variable preset

Required OAuth scopes

prompts:presets:write

JSON request body

Field	Type	Required	Rules
name	string	Yes	length: 1–120
templateTitle	string	No	length: 0–200
promptText	string	Yes	length: 1–20000
values	object	Yes	properties: 0–100
generationId	string	No	length: 0–191
generatedVersionId	string	No	length: 0–191

Responses

200 Success400 401 403 429 500

get/prompt-presets/{id}Get an owned prompt variable preset

Required OAuth scopes

prompts:presets:read

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

patch/prompt-presets/{id}Update a prompt variable preset

Required OAuth scopes

prompts:presets:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

JSON request body

Field	Type	Required	Rules
name	string	No	length: 1–120
values	object	No	properties: 0–100

Responses

200 Success400 401 403 404 429 500

delete/prompt-presets/{id}Delete a prompt variable preset

Required OAuth scopes

prompts:presets:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

post/prompt-presets/{id}/renderRender a prompt preset with variable overrides

Required OAuth scopes

prompts:presets:read

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

JSON request body

Field	Type	Required	Rules
values	object	No	properties: 0–100

Responses

200 Success400 401 403 404 429 500

get/operationsList AI operations

Required OAuth scopes

operations:read

Parameters

Name	Location	Type	Required	Rules
status	query	string	No	allowed: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED
kind	query	string	No	length: 0–100
limit	query	integer	No	default: 25; range: 1–100
cursor	query	string	No	—

Responses

200 Success400 401 403 429 500

get/operations/{id}Get an AI operation

Required OAuth scopes

operations:read

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

delete/operations/{id}Cancel a pending AI operation

Required OAuth scopes

operations:cancel

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 429 500

post/uploadsCreate a presigned temporary upload

Required OAuth scopes

uploads:write

JSON request body

Field	Type	Required	Rules
scope	string	Yes	allowed: analysis, refinement, feedback, generation, reverse_image, reverse_video
filename	string	Yes	length: 1–255
contentType	string	Yes	length: 1–100; Images: image/jpeg, image/png, image/webp, image/gif. reverse_video: video/mp4, video/quicktime, video/webm.
size	integer	Yes	range: 1–unlimited; Maximum 5 MB for images and 100 MB for reverse_video.

Responses

200 Success400 401 403 429 500 503

get/uploads/{id}Get an upload

Required OAuth scopes

uploads:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

delete/uploads/{id}Delete an unconsumed upload

Required OAuth scopes

uploads:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 429 500 503

post/uploads/{id}/completeValidate and complete an uploaded object

Required OAuth scopes

uploads:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 410 429 500 503

get/historyList product history

Required OAuth scopes

history:read

Parameters

Name	Location	Type	Required	Rules
type	query	string	No	allowed: generation, optimization, refinement; default: optimization
search	query	string	No	length: 0–200
limit	query	integer	No	default: 25; range: 1–100
offset	query	integer	No	default: 0; range: 0–unlimited

Responses

200 Success400 401 403 429 500

get/history/{type}/{id}Get a history item

Required OAuth scopes

history:read

Parameters

Name	Location	Type	Required	Rules
type	path	string	Yes	allowed: generation, optimization, refinement
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

patch/history/{type}/{id}Rename a history item

Required OAuth scopes

history:manage

Parameters

Name	Location	Type	Required	Rules
type	path	string	Yes	allowed: generation, optimization, refinement
id	path	string	Yes	length: 1–191

JSON request body

Field	Type	Required	Rules
title	string	Yes	length: 1–180

Responses

200 Success400 401 403 404 429 500

delete/history/{type}/{id}Delete a history item

Required OAuth scopes

history:manage

Parameters

Name	Location	Type	Required	Rules
type	path	string	Yes	allowed: generation, optimization, refinement
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

get/library/itemsList Prompt Library items

Required OAuth scopes

library:read

Parameters

Name	Location	Type	Required	Rules
scope	query	string	No	allowed: my, community, official, saved, upvoted; default: my
query	query	string	No	length: 0–200
category	query	string	No	length: 0–120
models	query	string	No	Comma-separated model names.
sort	query	string	No	allowed: recent, top; default: recent
page	query	integer	No	default: 1; range: 1–unlimited
pageSize	query	integer	No	default: 30; range: 1–30

Responses

200 Success400 401 403 429 500

post/library/itemsCreate a private Prompt Library item

Required OAuth scopes

library:write

JSON request body

Field	Type	Required	Rules
title	string	Yes	length: 1–90
promptText	string	Yes	length: 1–20000
description	string	No	length: 0–400
whatThisPromptDoes	string	No	length: 0–1500
tipsForThisPrompt	string	No	length: 0–1500
howToUsePrompt	string	No	length: 0–1500
recommendedModels	array<string>	Yes	items: 1–8
category	string	Yes	length: 1–120
exampleText	string	No	length: 0–5000
tokenEstimate	object	No	—
tokenEstimate.input	integer	No	range: 0–unlimited
tokenEstimate.output	integer	No	range: 0–unlimited
visibility	string	No	value: private; default: private

Responses

200 Success400 401 403 429 500

get/library/items/{id}Get a Prompt Library item

Required OAuth scopes

library:read

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

patch/library/items/{id}Update an owned item

Required OAuth scopes

library:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

JSON request body

Field	Type	Required	Rules
title	string	No	length: 1–90
promptText	string	No	length: 1–20000
description	string	No	length: 0–400
whatThisPromptDoes	string	No	length: 0–1500
tipsForThisPrompt	string	No	length: 0–1500
howToUsePrompt	string	No	length: 0–1500
recommendedModels	array<string>	No	items: 1–8
category	string	No	length: 1–120
exampleText	string	No	length: 0–5000
tokenEstimate	object	No	—
tokenEstimate.input	integer	No	range: 0–unlimited
tokenEstimate.output	integer	No	range: 0–unlimited

Responses

200 Success400 401 403 404 409 429 500

delete/library/items/{id}Delete an owned item

Required OAuth scopes

library:write

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

post/library/items/{id}/savedToggle saved state

Required OAuth scopes

library:interact

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 429 500

post/library/items/{id}/voteToggle vote

Required OAuth scopes

library:interact

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 429 500

post/library/items/{id}/publishPublish an owned item

Required OAuth scopes

library:publish

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 409 429 500

delete/library/items/{id}/publishMake an owned item private

Required OAuth scopes

library:publish

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

get/webhook-endpointsList webhook endpoints

Required OAuth scopes

webhooks:manage

Responses

200 Success400 401 403 429 500

post/webhook-endpointsCreate an endpoint; secret is returned once

Required OAuth scopes

webhooks:manage

JSON request body

Field	Type	Required	Rules
url	string	Yes	format: uri; length: 0–2048; Must be a public HTTPS URL.
description	string	No	length: 0–300
events	array<string>	Yes	items: 1–7

Responses

200 Success400 401 403 409 429 500 503

get/webhook-endpoints/{id}Get a webhook endpoint

Required OAuth scopes

webhooks:manage

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

post/webhook-endpoints/{id}Send a webhook.test delivery

Required OAuth scopes

webhooks:manage

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500 503

patch/webhook-endpoints/{id}Update an endpoint or rotate its secret

Required OAuth scopes

webhooks:manage

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

JSON request body

Field	Type	Required	Rules
url	string	No	format: uri; length: 0–2048; Must be a public HTTPS URL.
description	string	No	length: 0–300
events	array<string>	No	items: 1–7
enabled	boolean	No	—
rotateSecret	boolean	No	—

Responses

200 Success400 401 403 404 429 500 503

delete/webhook-endpoints/{id}Delete an endpoint

Required OAuth scopes

webhooks:manage

Parameters

Name	Location	Type	Required	Rules
id	path	string	Yes	length: 1–191

Responses

200 Success400 401 403 404 429 500

Authentication

REST accepts a scoped PrompTessor API key or OAuth access token in the Authorization: Bearer … header. MCP uses OAuth only. See Authentication & scopes for the complete lifecycle and scope catalog.

Machine-readable contract

Generate clients, validate payloads, or import the API into your preferred tooling using the canonical OpenAPI JSON document.