API guide and examples

Your account and API key

Sign up with a username and password. Save the API key and recovery code when shown. You can use the workbench immediately, or send the key in the Authorization: Bearer header from your application.

Free accounts have daily word, request, and AI-call limits. The signup page lists the current allowances, and GET /v1/usage reports yours. AI calls also share a service-wide daily allowance. Retrying a rewrite or adding meaning review uses more calls. Daily limits reset at midnight UTC; request-per-minute limits reset at the next UTC minute.

You can replace or revoke your key on the account page. A new key immediately replaces the old one, so update any scripts that use it. Rotating a key doesn't reset usage or remove profiles. Save your recovery code: there is no email password reset.

The base URL is https://unslopapi.vercel.app. Send JSON with Content-Type: application/json and your key in the Authorization: Bearer header. Keep keys in your server or local environment, not in public website code.

Save the analysis example below as analysis.json. Set UNSLOP_KEY in your environment, then run:

curl --fail-with-body https://unslopapi.vercel.app/v1/analyze \
  -H "Authorization: Bearer $UNSLOP_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @analysis.json

This request runs deterministic analysis and makes no AI calls. A rewrite that passes its gate and starts generation sends original excerpts and guidance to the selected providers. Each model attempt consumes one account AI call. Skipped rewrites still count as requests and consume the submitted-word allowance.

These are request bodies, not recorded responses or promises about a model's output. Save the one you need to a JSON file and use the matching endpoint in the command above.

Analyze a draft without AI

POST /v1/analyze. The ceiling asks whether the estimated grade is at most 8; easier text passes.

{
  "text": "It's worth noting that we fixed the search page. Your saved filters now work again. You can open the page, choose a filter, and see the matching notes without setting it up again.",
  "genre": "technical",
  "allow_ai": false,
  "include": ["score", "quality", "explain", "inspect"],
  "constraints": { "readability_ceiling": 8 }
}

Request a limited rewrite

Every AI rewrite, including AI proofreading, first checks the original. By default it needs at least 50 prose words and a style score of 20/100. Set rewrite_gate.threshold and rewrite_gate.minimum_words per request to change the cutoffs, or rewrite_gate.enabled: false to bypass them while still scoring the original. If the enabled gate fails, status: "skipped" returns the original with zero generation or meaning-review calls. Free-text instructions and voice profiles cannot override these structured settings. Ordinary deterministic proofreading is unaffected. This is a provisional editing threshold, not a validated authorship test.

POST /v1/rewrite. The default mixed provider alternates OpenAI and Anthropic. Each call proposes one small patch against the original text; the server assembles them. Select openai or anthropic to restrict processing to one provider. This example allows four generation calls, including any retries, plus one meaning review.

{
  "text": "It's worth noting that we fixed the search page. Your saved filters now work again. You can open the page, choose a filter, and see the matching notes without setting it up again.",
  "provider": "mixed",
  "rewrite_gate": { "enabled": true, "threshold": 5, "minimum_words": 30 },
  "micro": { "max_calls": 4, "max_span_words": 8, "max_span_chars": 60 },
  "allow_ai": true,
  "semantic_review": true,
  "retry_on_failure": true,
  "genre": "technical",
  "instructions": "Keep the facts. Remove unnecessary introductions. Keep the term saved filters.",
  "constraints": {
    "max_change_ratio": 0.15,
    "readability_ceiling": 8,
    "protected_terms": ["saved filters"],
    "preserve_numbers": true
  }
}

The example lowers the gate to a score of 5 and 30 words for a short passage. Omit rewrite_gate to keep the defaults of 20 and 50. Short-text scores are less informative. A tight change budget and a demanding reading target may conflict. If the candidate can't meet both, the API returns the original. It never silently loosens your limits.

Check a revision you already have

POST /v1/verify. This example uses code only. Changing 12 to 13 should fail the number-preservation check even though the edit is small.

{
  "original": "We shipped 12 fixes on Friday.",
  "revised": "We shipped 13 fixes on Friday.",
  "allow_ai": false,
  "constraints": { "max_change_ratio": 0.35, "preserve_numbers": true }
}

Save explicit writing preferences

POST /v1/profiles. The returned id can be supplied as profile_id on later analysis or rewrite requests.

{
  "name": "Plain project updates",
  "genre": "technical",
  "instructions": "Use direct language. Preserve qualifications and technical terms.",
  "rules": [{
    "id": "prefer.use",
    "type": "prefer",
    "phrase": "utilize",
    "replacement": "use",
    "description": "Prefer the simpler word when it fits.",
    "auto_fix": false
  }],
  "samples": [],
  "defaults": { "max_change_ratio": 0.35 }
}

Profiles are saved in your workspace. To replace or delete one, send its current revision in the X-Profile-Revision header. Request rules override profile rules with the same ID, and request constraints override profile defaults.

Put instructions in instructions and approved prose in samples. Profile import proposes rules for review; it does not save them automatically. Profile defaults hold constraints only. Supply gate settings, micro limits, provider selection, and review preferences on each request.

Analysis fields below are at the top level of /v1/analyze. A rewrite includes them under before and after, unless return_analysis: false. The individual /score, /quality, and /explain endpoints return their selected object directly.

Rewrite statuses: skipped means the score gate failed; unchanged means no change was returned; partially_rewritten means accepted changes with unreviewed spans; rewritten means accepted changes after all planned spans were reviewed; constraints_unsatisfied means final validation or meaning review rejected the candidate. Per-call acceptance in attempts does not override the final accepted value. A completed scan does not prove every possible improvement was found.

HTTP 200 can include accepted: false and status: "constraints_unsatisfied". That means the service ran successfully and rejected the edit. Rejected candidate differences remain in validation.comparison for diagnosis; do not automatically apply them.

On /v1/verify, constraints_satisfied covers mechanical checks only. If you enable AI review there with allow_ai: true and semantic_review: true, read the separate semantic result too.

The table lists top-level rewrite fields. Gate and micro settings use their own nested objects; edit budgets, reading targets, output limits, and preservation flags belong inside constraints. Unknown fields are rejected. Omitted object fields keep their defaults.

/proofread defaults to reporting findings. apply:true applies conservative deterministic corrections. Adding allow_ai:true uses the score gate and AI micro-editing, with the default micro limits and one provider (OpenAI unless specified). It does not accept rewrite-only fields such as micro, instructions, or provider:"mixed"; use /rewrite for those controls. /review chooses its model with reviewer; /verify uses provider for optional meaning review. Neither is blocked by the rewrite gate.

• constraints.max_change_ratio charges added plus removed prose tokens against the original. The rewrite default is 0.15, unless overridden by your profile or request. A word replacement charges both sides; whitespace does not count toward this ratio.
• rewrite_gate works on /score, /analyze, /rewrite, and AI /proofread. Fields: enabled (boolean, default true), threshold (0–100, default 20), and minimum_words (integer 0–20,000, default 50). Omitted fields keep their defaults. Zero words disables the size requirement; zero score permits any scorable prose. Text with no scorable prose still fails an enabled gate. The response echoes the settings and reason. Request settings do not change other requests.
• micro.max_calls: 1–12, default 4. Meaning review adds at most one call. Remaining account allowance can reduce the generation budget. micro.max_span_words: 1–24, default 8; micro.max_span_chars: 1–160 Unicode code points, default 60. Both sides of each replacement, and adjacent patches separated only by whitespace, must fit these limits. These are size limits, not watermark guarantees.
• constraints.max_edit_count limits contiguous character-diff regions. constraints.max_edit_size limits the larger side of each region in Unicode code points. A replacement can produce several regions.
• Each source or revision text field allows up to 20,000 UTF-16 units. The total JSON body limit is 256 KB.
• constraints.max_output_words and constraints.max_output_chars cap the full output, including code and markup. The character cap uses Unicode code points.
• Finding and protected-span offsets use half-open UTF-16 ranges: start is included, end is excluded. This matches JavaScript string slicing. An emoji such as 😀 uses two UTF-16 units but one Unicode code point. Don't split its pair.
• Choose only one of target_age, readability_target, or readability_ceiling. An explicit choice replaces the profile's age/grade/ceiling default. Exact targets use a tolerance, default 1 grade. Ceilings do not add tolerance.
• target_age accepts whole ages 6 through 18 and approximates grade as age minus 5. Reading grades need at least 30 words and two sentences. See the limits of readability formulas.
• writing_complexity_target accepts simple below grade 8, moderate from 8 to below 13, or complex at 13 and above. This describes the text rather than the author's ability.
• Numbers and quotations are protected by default. Markdown formatting protection is also on by default when format: "markdown". Micro-edits preserve paragraph breaks even if that protection is disabled. The preserve_paragraph_breaks option remains useful when verifying an independently edited revision.
• writing_samples accepts up to four prose samples per request, up to 5,000 UTF-16 units each. Descriptive comparisons require two samples totaling at least 20 sentences; they are not hard voice constraints.

These request settings complement provider, micro, constraints, rules, writing_samples, instructions, tone, audience, semantic_review, retry_on_failure, and response-detail flags. Account quotas, maximum request size, available models, and server-enforced upper bounds remain service limits. The exact fields and ranges are in OpenAPI. GET /v1/capabilities reports the configured models and engines. This avoids relying on a model name copied from an older example.

When reporting a problem, keep the request_id or X-Request-Id value. Don't include your key. Share submitted text only if you intend the recipient to see it.

Deterministic analysis runs on the server without a model call. Rewriting and optional review send the relevant text and guidance to the chosen providers; mixed editing uses both OpenAI and Anthropic. Saved profiles persist in workspace storage; prepaid requests may briefly cache response text for retries. See billing and retention. See where your text goes.

Public prepaid accounts allow 20 requests per minute, 500 requests per day, 100,000 submitted words per day and 100 model calls per day. When billing is disabled, the trial allowance is 10,000 words and 5 calls per day. Individual keys can have different limits. GET /v1/usage reports yours. All submitted string values, including samples, instructions, and rule text, count toward words; failed provider attempts count toward calls.

External detector or watermark requests require allow_external: true and an approved, configured provider. Reading the static reference pages makes no API or model calls. A score-gate skip uses no AI calls but still counts toward request and word allowances. Mixed mode may reach only one provider when its call budget is one; providers_used reports generation calls, and semantic_review.model identifies any reviewer. Retry and meaning review are off by default. Each patch-generation attempt counts as one call; retries use the generation budget and meaning review adds at most one call.