POST /polish

Analyse a draft deterministically and return the polished text with its diff. This endpoint does not consume words or anonymous trials.

Request

textstring

Required. 1 to 20,000 characters.

tonestring

neutral | warm | brief | formal | direct. Defaults to neutral.

returnstring

diff. Any other value is a 400 rather than a silent fallback.

saveboolean

Stores the result and returns a revision number. Defaults to false.

The body is validated strictly: an unknown field is a 400 invalid_request, not a silence. {"sav": true} has to be visible immediately, because a caller who believes they are persisting and are not is the worst of both worlds.

Example

cURL

curl https://api.genpolish.app/v1/polish \
  -H "Authorization: Bearer $GENPOLISH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "In today’s fast-paced world…", "tone": "warm"}'

Response

textstring

The polished draft.

diff[]token[]

Ordered tokens with op: del | ins | chg.

changes[]change[]

One entry per edit, with kind and rationale.

scoreobject

before and after, 0–100.

revisioninteger

Present only when save is true.

Nothing is applied for you

The endpoint returns proposals. Applying them is the caller’s decision, one change at a time.

Separate AI rewrite backend

AI rewriting is a separate, disabled-by-default backend capability. POST /v1/me/rewrites accepts a real session and { operationId, text, options }. POST /v1/anonymous/rewrites uses an existing anonymous cookie and { operationId, workspaceId, workspaceVersion, options }; the server loads the draft. Legacy API keys cannot select an account owner.

options.mode is natural, professional, concise or academic; options.preserve defaults to numbers, URLs, citations and Markdown. /rewrite and the dedicated /tools/ai-text-rewriter page use exactly the same AI editor and backend. They share three server-counted anonymous successes; a failure consumes none. Each successful account run consumes its input word count from the account allowance, including an unchanged result, spending monthly words, then bonus words, then purchased words. The homepage only transfers your draft. The five browser-only utilities remain free without an account; AI Text Rewriter is not one of them.

The response carries an operation and its state, not the legacy diff, Human score or individual suggestions to accept. Recover it using GET on the corresponding /rewrites/:id path or /rewrites?operationId=…. Results are retained for at most 24 hours, bounded also by anonymous identity expiry. An HTTP 202 means pending; an HTTP 200 operation can still be failed or expired. Check its status before using the result.

Both pages share one private persisted workspace, anonymous session or account credits, reservations, saved intention, recovery, account History and paywall. The editor saves your draft and settings for 24 hours from the last write when you submit or explicitly continue to signup or Billing. Claiming an anonymous workspace does not import its successes into account History. Conflicting drafts are never silently overwritten. Existing account History keeps successful originals and results for 90 × 24 hours; technical results still have their separate 24-hour limit.

/rewrite remains the canonical destination for authentication, History reopening, homepage handoff, signup/login and Checkout returns, and submissions without JavaScript. The tool page ignores the canonical doc, welcome, history/source, handoff and billing-return query parameters. Neither navigation, signup nor payment generates a rewrite automatically. A payment return URL grants no words: the server must recognize the payment. The shared editor adds no separate quota, payment destination, business service, API, SDK, database migration or cookie. Legacy gp_trial and gp_preview_profile cookies prove neither a real session nor credits.

save is not available on every deployment

A deployment that stores nothing answers 501 persistence_unavailable rather than returning a made-up revision number. Send save: false and keep the polished text yourself.

Next: GET /revisions