Edits Overview

The edits endpoint provides grammar, spelling, and stylistic edits for text. The endpoint is customizable through a dictionary and custom mappings. The Postman "Sample Code" does not require any coding.

As of November 2024, the default model is Sapling's Edits Large model, which catches 27% more errors with fewer false positives than the earlier 2024 Edits Small system.

Empirically, smaller models finetuned on customer-specific data outperforms larger models. If you expect 100 million or more characters in usage volume per month, please contact us for how we can develop custom models. Sapling also has existing prebuilt models for applications such as healthcare/medicine.

Demo

Request Edits POST

Sample Code

curl -X POST https://api.sapling.ai/api/v1/edits \
     -H "Content-Type: application/json" \
     -d '{"key":"<api-key>", "text":"Hi, how are you doing.", "session_id": "test session"}'

info

If you want to pretty-print JSON output so it's easier to read and you have Python installed, you can pipe command line outputs into | python -m json.tool.

Example: echo "{\"text\": \"Some text\"}" | python -m json.tool

info

The results you get should match those from pasting the text on https://sapling.ai/grammar-check

If the results do not match, check that you're not adding additional newlines or adding unnecessary character escaping (e.g. \\r or \\n) in your request.

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/edits',
            {
                "key": '<api-key>', // replace with your API key
                "session_id": 'test session',
                text,
            },
        );
        const {status, data} = response;
        console.log({status});
        console.log(JSON.stringify(data, null, 4));
    } catch (err) {
        const { msg } = err.response.data;
        console.log({err: msg});
    }
}

run('Hi, how are you doing.'); // replace with the text you want to analyze

import requests
from pprint import pprint

try:
    response = requests.post(
        "https://api.sapling.ai/api/v1/edits",
        json={
            "key": "<api-key>",
            "text": "Hi, how are you doing.",
            "session_id": "test session"
        }
    )
    resp_json = response.json()
    if 200 <= response.status_code < 300:
        edits = resp_json['edits']
        pprint(edits)
    else:
        print("Error: ", resp_json)
except Exception as e:
    print("Error: ", e)

# python -m pip install sapling-py

from sapling import SaplingClient
from pprint import pprint

api_key ='<api-key>'
client = SaplingClient(api_key=api_key)
edits = client.edits('Hi, how are you doing.', session_id="test_session")
pprint(edits)

// npm install @saplingai/sapling-js

import { Client } from "@saplingai/sapling-js/client";

const apiKey = '<api-key>';
const client = new Client(apiKey);
client
  .edits('Hi, how are you doing.')
  .then(function (response) {
    console.log(response.data);
  })

React full-stack integration
HTML quickstart

Sample Response

{
  "edits": [
    {
      "end": 22,
      "error_type": "R:PUNCT",
      "general_error_type": "Punctuation",
      "id": "4bb963a4-cc19-523e-9bb2-9e6b5a270bfc",
      "replacement": "doing?",
      "sentence": "Hi, how are you doing.",
      "sentence_start": 0,
      "start": 16
    }
  ]
}

Request Parameters

https://api.sapling.ai/api/v1/edits

HTTP method: POST

To avoid client side time-outs, we recommend breaking text longer than 4000 characters into chunks/paragraphs before sending to Sapling. However, the endpoint will accept requests of up to 50,0000 characters. Sapling offers a chunking endpoint you can use here. This endpoint will return HTTP Status 400 with feedback in the msg field if the request is invalid—e.g if the key is missing or incorrect.

The Edit API POST endpoint takes JSON parameters documented below:

key: String
32-character API key.

text: String
Text to process for edits.

session_id: String
Unique name or UUID of document or portion of text that is being checked.

user_id: Optional String
Use this along with the accept and reject endpoints to allow different users to maintain individual preferences.

lang: Optional String
Specifies language for grammar and spell checking.

Supported Languages

Specifies language for grammar and spell checking. Defaults to English, or the language specified in the dashboard.

Supported languages:

auto: Autodetect language
de: German (Deutsch)
el: Greek (Ελληνικά)
en: English (US/UK/CA/AU)
es: Spanish (Español)
fr: French (Français) (fr-fr and fr-ca coming soon)
it: Italian (Italiano)
jp: Japanese (日本語)
ko: Korean (한국어)
nl: Dutch (Nederlands)
pl: Polish (Polski)
pt: Portuguese (Português) (pt-pt and pt-br coming soon)
sv: Swedish (Svenska)
tl: Tagalog
zh: Chinese (中文)

variety: Optional String

Supported Varieties

This option is currently available for: English, Chinese (中文). Specifies regional English/Chinese spelling options. The setting defaults to the configuration in the Sapling dashboard.

Supported varieties:

English:

us-variety: American English
gb-variety: British English
au-variety: Australian English
ca-variety: Canadian English
null-variety: Don’t suggest any changes based on English variety

Chinese (中文)

s-variety: Simplified Chinese
t-variety: Traditional Chinese

auto_apply: Optional Boolean
Default is false. If true, result with have extra field applied_text containing text with edits applied.

neural_spellcheck: Optional Boolean
Default is false. If true, system will also apply more aggressive spellcheck to catch more spelling errors than the base system alone.

operations: Optional List of Strings
Default is []. Possible operations are described in the Postprocess documentation. This will run postprocessing on outputs before returning results so you can enforce stricter capitalization, punctuation, and whitespace removal.

ignore_edit_types: Optional List of Strings
Default is []. Possible types are:

articles_determiners: Do not suggest a or the and do not suggest removing a or the.
auxiliary_verbs: Do not suggest auxiliary verbs such as be, can, or will.
capitalization: Do not suggest capitalizations.
hyphens: Do not suggest hyphens such as in production ready -> production-ready.
punctuation: Do not suggest terminating punctuation such as . or ?.
whitespace: Do not suggest edits such as removing double spaces.

medical: Optional Boolean
Default is false. If true, the backend will apply Sapling's medical dictionary. You can test the medical spellcheck system here.

Response Parameters

The Edits POST endpoint returns JSON with parameters documented below:

edits: Array
Array of Edit objects for the text sent in the request.

Edit data structure:

{
  "id": <str, UUID>,           // Opaque edit id, used to give feedback
  "sentence": <str>,           // Unedited sentence
  "sentence_start": <int>,     // Offset of sentence from start of text
  "start": <int>,              // Offset of edit start relative to sentence
  "end": <int>,                // Offset of edit end relative to sentence
  "replacement": <str>,        // Suggested replacement
  "error_type": <str>,         // Error type, see "Error Categories"
  "general_error_type": <str>, // See "Error Categories"
}

Tips

Check the status code of the result and any error logs.
Unless you're sending very large requests, the requests should rarely fail or time out, but you can follow these instructions to implement a retry mechanism.
Use the accept/reject endpoints below if you would like Sapling to learn to stop making specific suggestions.
Follow the guidelines for applying edits.

Accept Edit POST

Use this API endpoint to have Sapling adapt its system over time.

Each suggested edit has an edit UUID. You can pass this information back to Sapling to indicate the edit suggestion was helpful. For each unique edit in each document, use the accept or reject API endpoint only once in total.

Request Parameters

import requests

key = '<api-key>'
edit_id = '<EDIT_ID>'

url = f'https://api.sapling.ai/api/v1/edits/{edit_id}/accept'
data = {
    'key': key,
    'session_id': 'Test Document UUID',
}

try:
    resp = requests.post(url, json=data)
    resp_json = resp.json()
    assert resp.status_code == 201
except Exception as e:
    print("Error: ", e)

https://api.sapling.ai/api/v1/edits/<edit_id>/accept

HTTP method: POST

Note that the edit_id is part of the URL. The Accept API POST endpoint takes a variety of JSON parameters documented below:

edit_id: String (UUID)
ID of an Edit.

key: String
32-character API key

session_id: String
Unique name or UUID of document or portion of text that is being checked.

user_id: String
Pass this in to associate the accept event with a specific user. This allows different users to maintain different preferences.

Response Parameters

HTTP status code 201.

Reject Edit POST

Use this API endpoint to have Sapling not recommend the same edit anymore.

Each suggested edit has an edit UUID. You can pass this information back to Sapling to indicate the edit suggestion was not helpful. For each unique edit in each document, use the accept or reject API endpoint only once in total.

Request Parameters

import requests

key = '<api-key>'
edit_id = '<EDIT_ID>'

url = f'https://api.sapling.ai/api/v1/edits/{edit_id}/reject'
data = {
    'key': key,
    'session_id': 'Test Document UUID',
}

try:
    resp = requests.post(url, json=data)
    resp_json = resp.json()
    assert resp.status_code == 201
except Exception as e:

https://api.sapling.ai/api/v1/edits/<edit_id>/reject

HTTP method: POST

Note that edit_id is part of the URL. The Reject API POST endpoint has JSON parameters documented below:

edit_id: String (UUID)
ID of an Edit.

key: String
32-character API key

session_id: String
Unique name or UUID of article or portion of text that is being checked

user_id: String
Pass this in to associate the reject event with a specific user. This allows different users to maintain different preferences.

Response Parameters

HTTP status code 201.

Edits Overview

Request Edits POST​

Sample Code​

Sample Response​

Request Parameters​

Response Parameters​

Tips​

Accept Edit POST​

Request Parameters​

Response Parameters​

Reject Edit POST​

Request Parameters​

Response Parameters​

Request Edits POST

Sample Code

Sample Response

Request Parameters

Response Parameters

Tips

Accept Edit POST

Request Parameters

Response Parameters

Reject Edit POST

Request Parameters

Response Parameters