Skip to main content

OpenAPI Specification

Sapling publishes a machine-readable OpenAPI 3.1 description of its REST API:

https://api.sapling.ai/openapi.json

The same document is also served at https://api.sapling.ai/api/v1/openapi.json. Fetching it does not require an API key. It can be loaded cross-origin from any website, and it is cached for up to an hour.

curl -s https://api.sapling.ai/openapi.json -o sapling-openapi.json

What it covers​

The spec describes the public endpoints you can call with an API key:

  • Language endpoints: grammar and spelling (edits, spellcheck), rephrase and paraphrase, summarize, translate, simplify, autocomplete, AI-content detection (text, PDF and Word files), language detection, PII, named entities, content safety, profanity, tone, sentiment, statistics, writing quality, SEO, classification, extraction, style guides, and similar terms.
  • Supporting endpoints: accept and reject feedback for edits and completions, the custom dictionary, custom mappings and filters, saved style-guide rule sets, PDF and Word text extraction and chunking, account status, usage reporting, and version and liveness probes.

Operations are grouped by tag (proofreading, generation, detection, analysis, files, account, service), so generated clients get one API class per group. Team Management endpoints are not in the spec yet.

Each operation lists its request body schema, authentication options, and the status codes and headers it can return: rate-limit headers, 402 Payment Required, 429 backoff, and endpoint-specific cases such as the 502 from model-backed endpoints. Success responses are described at the level of the top-level JSON shape. For field-by-field response documentation and examples, see each endpoint's page in these docs. The spec links to them.

The operationId of each language endpoint matches the corresponding tool name on the Sapling MCP Server (for example, sapling_grammar_check for POST /api/v1/edits), so agents can cross-reference the two.

Authentication​

The spec declares an HTTP bearer scheme. Send your API key as Authorization: Bearer YOUR_API_KEY. As with every Sapling request, you can instead send the key as a key parameter — in the JSON body of operations that take one, or in the query string of the GET and DELETE operations. Each operation's schema declares the key parameter in the right location, so the spec marks the bearer header as optional.

Using the spec​

Postman or Insomnia​

In Postman, choose Import → Link and paste https://api.sapling.ai/openapi.json. Postman creates a collection with one request per endpoint. Set the collection's authorization to Bearer Token with your API key.

In Insomnia, choose Create → Import → URL and paste the same address.

Browse it interactively​

Open the spec in Swagger Editor to browse every operation and its schemas. You can also send test requests from the Try it out panel after you enter your API key under Authorize.

Generate a typed client​

Any OpenAPI 3.1 code generator works. For example, with openapi-generator:

# Python
npx @openapitools/openapi-generator-cli generate \
  -i https://api.sapling.ai/openapi.json -g python -o sapling-client

# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate \
  -i https://api.sapling.ai/openapi.json -g typescript-fetch -o sapling-client

Or generate TypeScript types only with openapi-typescript:

npx openapi-typescript https://api.sapling.ai/openapi.json -o sapling.d.ts

Sapling also maintains hand-written Python and JavaScript SDKs. Use those unless you need a client in another language.

ChatGPT Actions and agent frameworks​

Many agent frameworks can turn an OpenAPI document into callable tools:

  • Custom GPTs (ChatGPT Actions): In the GPT editor, add an action, choose Import from URL and paste the spec URL. Under Authentication, choose API Key → Bearer and enter your Sapling API key. GPT Actions cap the number of operations one action can hold. If the import is rejected, or you want a focused GPT, delete the operations you don't need from the imported schema.
  • LangChain, LlamaIndex, Semantic Kernel, and similar frameworks ship OpenAPI toolkits that accept the spec URL.
  • If your assistant supports the Model Context Protocol, the Sapling MCP Server is usually the simpler route. It exposes the same language endpoints as ready-made tools.

Tool calls made this way are ordinary API requests. They count against your API key's rate limits, quota, and billing like any other call.

Rate limits and errors​

The spec's top-level description documents the shared contract, and each operation declares the exact statuses it can return:

  • Rate-limited operations return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. X-RateLimit-Reset is the number of seconds until the rate limit resets, not a timestamp.
  • 429 responses carry Retry-After and a numeric retry_after body field. If retry_after is missing, the request is too large to ever succeed, so don't retry it unchanged.
  • Most errors are JSON with a msg field. Request-validation 400s are plain text, so treat the status code as authoritative.

See Rate Limits for the limits themselves.

Self-hosted deployments​

On-premises deployments running a current Sapling release serve their own copy at https://<your-sapling-host>/openapi.json. That copy's servers entry points to your deployment rather than api.sapling.ai, so clients generated from it send requests (and your text) to your own infrastructure. If your deployment sits behind a proxy that hides its public hostname, your administrator can set the OPENAPI_SERVER_URL environment variable on the web service to override the advertised address. A deployment that disables API rate limiting serves a spec without rate-limit headers or 429 responses.