Reference

HTTP API

Base URL https://promptflowengine.com/api/v1. JSON in, JSON out. No authentication and nothing is stored; prompt text is never logged. Every response carries an x-request-id header.

For bulk or sensitive work, run the same engine locally with the CLI: no network, no rate limits.

Endpoints

Method	Path	Body	Returns
GET	`/health`	—	status, engine and API versions
GET	`/models`	—	model catalogue with encodings and reference prices
GET	`/rules`	—	rule catalogue, dimensions, penalties
POST	`/analyze`	`prompt`, `model?`	findings, quality, tokens, security, requirements, intent
POST	`/validate`	`prompt`	`valid` (no critical findings), findings
POST	`/optimize`	`prompt`, `model?`, `mode?`, `goal?`, `tokenBudget?`	selected candidate, all candidates with verification, changes, diff, deltas, suggestions
POST	`/compare`	`a`, `b`, `model?`	diff, token/cost/quality deltas, findings resolved and introduced
POST	`/tokens`	`prompt`, `model?`	token count, method, per-section counts, estimated cost
POST	`/scan`	`prompt`	injection risk and signatures, sensitive-data counts and offsets, undelimited variables
POST	`/sanitize`	`text`	text with sensitive values replaced by placeholders

mode: conservative | balanced | structured. goal: tokens | quality | balanced. model: any id from /models (default gpt-4.1).

Example

curl

curl -s https://promptflowengine.com/api/v1/optimize \
  -H 'content-type: application/json' \
  -d '{"prompt":"Please summarize the notes. Please summarize the notes.","mode":"balanced"}' \
  | jq '{selected: .selected.text, tokenDelta, changes: [.changes[].title]}'

With "goal":"tokens" the engine would instead keep Please summarize the notes.: a sentence-initial Summarize costs two tokens, so that candidate is one token cheaper.

response (abridged, real output)

{
  "selected": "Summarize the notes.",
  "tokenDelta": -4,
  "changes": ["Removed repeated sentences", "Removed filler and politeness phrases"]
}

Limits

Request body up to 256 KB; each text field up to 100,000 characters.
60 POST requests per minute per client IP. Over the limit you get 429 with retry-after: 60.
CORS is open (*) without credentials, so browsers can call the API directly.

Errors

error envelope

{ "error": { "type": "invalid_request", "message": "\"prompt\" is required.", "requestId": "…" } }

Status	type
400	`invalid_request`: missing or wrong-typed field, bad JSON, wrong content type
404	`not_found`: unknown endpoint or API version
405	`method_not_allowed`
413	`payload_too_large`
429	`rate_limited`
500	`internal_error` (no internal details are exposed)