# Sapling

> Sapling (sapling.ai) is a language-AI platform: an HTTP API, SDKs and an MCP server for grammar and spelling correction, AI-generated text detection, rephrasing, summarization, translation, classification, extraction, PII redaction, content safety and other text analysis, plus a writing assistant for browsers, Google Docs, Outlook and Word.

This is the machine-readable front page of https://sapling.ai for AI agents. The human-facing page is https://sapling.ai/. A site map for agents is at https://sapling.ai/llms.txt and the developer docs index is at https://sapling.ai/docs/llms.txt.

## When to use Sapling

Reach for Sapling when a task needs one of these, programmatically and at volume:

- **Proofread text**: grammar, spelling and punctuation corrections with exact character offsets you can apply (`POST /api/v1/edits`, or the spelling-only `POST /api/v1/spellcheck`).
- **Detect AI-generated text**: an overall score, a `verdict` (`human`, `mixed` or `ai`) with the AI-scored `segments`, a `low_confidence` flag for short or list-formatted inputs, and per-sentence scores (`POST /api/v1/aidetect`). Pass `zero_retention: true` to keep no copy of the text (no cached result, no certificate `hash`, usage logged without the text); it is also accepted by `/api/v1/url-aidetect` and, in `jsonParams`, `/api/v1/file-aidetect`. Supports English, Spanish, Portuguese, French, German, Italian, Dutch, Japanese, Polish, Chinese, Arabic, Russian, Swedish, Korean, Turkish and Romanian; the language is detected automatically or set with the `lang` parameter. To check a public web page, send its URL instead (`POST /api/v1/url-aidetect`, or the MCP tool `sapling_ai_detect_url`): Sapling fetches the page and scores only its main text, without the navigation, footers and other boilerplate.
- **Rewrite text**: paraphrase, change formality or tone, shorten, expand or simplify to a reading level (`/api/v1/rephrase`, `/api/v1/simplify`).
- **Analyze text**: tone, sentiment, readability statistics, writing-quality rubric, SEO metadata, language detection with a `reliable` flag that says when the result is safe to act on, plus the text's writing `script` (`/api/v1/tone`, `/api/v1/sentiment`, `/api/v1/statistics`, `/api/v1/quality`, `/api/v1/seo`, `/api/v1/langdetect`).
- **Structure text**: zero-shot classification into your own labels, typed field extraction with evidence spans, named-entity recognition, PII detection and redaction (`/api/v1/classify`, `/api/v1/extract`, `/api/v1/ner`, `/api/v1/pii`).
- **Work on documents**: upload a PDF, DOCX, PPTX, ODT, TXT, Markdown or HTML file (up to 30MB) to score it for AI-generated text, extract typed fields from it or summarize it, without extracting its text yourself (`/api/v1/file-aidetect`, `/api/v1/file-extract`, `/api/v1/file-summarize`).
- **Moderate or translate**: content-safety scoring and translation across 170+ languages (`/api/v1/safety`, `/api/v1/translate`).
- **Enforce a house style**: check text against your own style rules (`/api/v1/styleguide`).
- **Autocomplete**: sentence completion (`/api/v1/complete`).

Sapling is not a general chat model. Use it for these specific text operations, where you need deterministic JSON output, offsets and enterprise controls (SOC 2 Type II, HIPAA BAA, zero data retention, self-hosting).

## API

- Base URL: `https://api.sapling.ai`
- Every text-processing endpoint is a `POST` with a JSON body and a JSON response. There are two exceptions:
  - The document-upload endpoints (`/api/v1/file-aidetect`, `/api/v1/file-extract`, `/api/v1/file-summarize`) take `multipart/form-data`: a `file` part and a `jsonParams` field holding the JSON options.
  - The `GET` health checks (`/api/v1/version`, `/api/v1/liveness`).
- OpenAPI 3.1 description: https://sapling.ai/openapi.json (the canonical copy is https://api.sapling.ai/api/v1/openapi.json)
- API catalog (RFC 9727): https://sapling.ai/.well-known/api-catalog
- Reference docs: https://sapling.ai/docs/api/

Minimal request:

```bash
curl -X POST https://api.sapling.ai/api/v1/edits \
  -H "Authorization: Bearer $SAPLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Lets get started.", "session_id": "my-session"}'
```

Rate-limited responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds). A `429` carries `Retry-After`.

## Authentication

- **API key**: register at https://sapling.ai/user/register, then create a key self-serve at https://sapling.ai/api_settings. Send it as `Authorization: Bearer <key>`, or as a `key` field in the JSON body. New keys get a free developer quota of 50,000 characters per day (250,000 per month).
- **OAuth 2.0** (authorization code + PKCE S256, dynamic client registration): authorization-server metadata is at https://api.sapling.ai/.well-known/oauth-authorization-server. The scope is `sapling:api`. The hosted MCP server uses this flow, so users never paste a key into an agent.

Details: https://sapling.ai/auth.md

Sandbox: the free trial key is the test environment. It is never charged, and almost every endpoint only reads the text you send. `GET /api/v1/version` and `GET /api/v1/liveness` need no key. The few calls that change stored state (dictionary, custom mappings, saved rule sets, semantic-search entries, edit feedback, team admin) are listed at https://sapling.ai/docs/sandbox/

## MCP server

- Hosted (Streamable HTTP): `https://mcp.sapling.ai/mcp`. Sign in with OAuth or send an API key as a bearer header.
- Local (stdio): `npx -y @saplingai/mcp-server` with `SAPLING_API_KEY` in the environment.
- Tool results: the endpoint's JSON response as a text block, and also as `structuredContent` when it is a JSON object (hosted server; local server after `@saplingai/mcp-server` 0.1.10). Read typed fields from `structuredContent` when your client exposes it; otherwise parse the text block.
- Tool errors: `isError: true` with the API status and message. When the call was rate limited and waiting will clear it, the error says how long: the hosted server ends the text with `Wait at least N seconds before retrying.`, and the local server (after 0.1.10) adds a top-level `retry_after` in seconds. No wait time on a `500`, `502` or `400` whose message starts with `Unexpected error` means a temporary failure: retry once or twice with a short backoff. Any other error without a wait time won't succeed by retrying the same call.
- Server card: https://sapling.ai/.well-known/mcp/server-card.json
- Setup guide: https://sapling.ai/docs/mcp/

Claude Code: `claude mcp add --transport http sapling https://mcp.sapling.ai/mcp`

## SDKs

- JavaScript / TypeScript: `npm install @saplingai/sapling-js` (https://www.npmjs.com/package/@saplingai/sapling-js)
- Python: `pip install sapling-py` (https://pypi.org/project/sapling-py/)
- Embeddable editor SDK for web apps: https://sapling.ai/docs/sdk.md

## Pricing

Free developer quota, then usage-based per-character pricing (for example, grammar edits start at $0.025 per 1,000 characters). Writing-assistant plans are Free, Pro ($25/month) and Enterprise. Machine-readable summary: https://sapling.ai/pricing.md. Full per-endpoint table: https://sapling.ai/docs/api/pricing/

## More

- Security and compliance: https://sapling.ai/security
- HIPAA: https://sapling.ai/hipaa
- On-premises / self-hosted: https://sapling.ai/docs/onprem/overview/
- Integrations: https://sapling.ai/integrations
- Contact: support@sapling.ai (support), sales@sapling.ai (sales), https://sapling.ai/contact