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 the original text and guidance to external AI services. 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 }
}

Edit a complete draft

Rewrites replace common count-led headings and paired-count slogans with descriptive wording. The count_framing_frequency check permits at most min(floor(original_occurrences × 0.05), floor(output_words / 2000)) matches, with at least 2,000 words between retained matches. Short drafts permit none. Detection is heuristic; factual quantities in prose, dates, versions, list numbering and protected content are not targets. Required numbers must be preserved, not deleted to satisfy style. A failed check enters the correction attempt; if it still fails, the original returns without a charge.

POST /v1/rewrite defaults to mode: "document". One call edits the entire draft, then a separate review checks factual meaning. Mechanical constraints protect numbers, quotations and protected content. One correction attempt is allowed after a failed check. If no candidate passes, the original is returned with no customer charge.

Choose model_level: low, medium, high or max. Medium is the default. Model identities remain private. The style gate is disabled by default; set rewrite_gate.enabled: true to use its score and word-count thresholds. A configured gate skip costs nothing.

{
  "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.",
  "mode": "document",
  "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": 1.5,
    "readability_ceiling": 8,
    "protected_terms": ["saved filters"],
    "preserve_numbers": true
  }
}

The score gate is disabled by default, so obvious filler can be edited even when the style score is low. Set rewrite_gate.enabled to true to require its score and length thresholds. 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, model level, 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 the complete candidate passed validation and meaning review in document mode, or all planned spans were reviewed in micro mode; 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. Document mode is the default. Set mode: "micro" for the legacy phrase editor. 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. It does not accept rewrite-only fields such as micro, instructions; use /rewrite for those controls. /review and optional meaning review in /verify use AI services selected by Unslop. Neither is blocked by the rewrite gate.

• constraints.max_change_ratio charges added plus removed prose tokens against the original. The document rewrite default is 1.5; micro mode defaults to 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.
• In mode: "micro" only, 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 micro, constraints, rules, writing_samples, instructions, tone, audience, semantic_review, retry_on_failure, and response-detail flags. Account quotas, maximum request size, available features, and server-enforced upper bounds remain service limits. The exact fields and ranges are in OpenAPI. GET /v1/capabilities reports available features and limits. Model identities and provider selection are not exposed by the API.

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.

Run history

GET /v1/history reports workspace writing-run totals by level and the latest 100 score, analyze, rewrite and proofread results. Rows contain timestamps, levels, outcomes, before/after style scores and settled charges, without document text. Counts start when history is enabled; older runs are not backfilled. Billing replays count once. A null charge means no prepaid charge was reported. This history is separate from billing records and is removed when the account is deleted.

Deterministic analysis runs on the server without a model call. Rewriting and meaning review send the relevant text and guidance to external AI services selected by Unslop. 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. micro_editing reports generation and review call counts; semantic_review reports meaning-review findings. Document editing always checks meaning and can make one correction attempt. Each generation or review counts toward the account allowance. Micro mode has separate phrase-edit limits.