Advanced Edits

Sapling provides customizable proofreading settings that go beyond regular spelling and grammar checking. These include suggestions around making text simpler and more confident, as well as edits around DEI. The Advanced Edits settings are configurable for your account (here) as well as on a per API call level (documented below) because these suggestions may not be applicable to all styles of writing. Advanced Edits are currently only available for English.

You can find a demo of the sort of suggestions Advanced Edits generates here.

Adverbs

Adverbs can usually be replaced either with a stronger verb.

He ran quickly towards the exit. -> He dashed towards the exit.

Simplifications

Consider replacing complex phrases with a simpler one with the same meaning.

A number of people feel this way. -> Many people feel this way.

Hard to read

Sentences that are too long can be hard to read. Consider breaking them up for clarity.

In the age of digital technology and social media, it's becoming increasingly important for individuals to be aware of their online presence and the impact that their actions and words can have on others.

->

In the digital age, it's vital to be aware of how our online presence and actions can impact others.

Passive Voice

Sentences in the active voice are usually more concise and clear.

The ball was kicked by him. -> He kicked the ball.

Qualifiers

Qualifiers lead to less confident communication. Consider removing them.

I was wondering if we can meet tomorrow? -> Can we meet tomorrow?

DEI

Sapling breaks DEI into the following categories. Example of each are also given:

• Gender Pronouns

  Prefer "they"/"them" over "he"/"him"

• Gender Nouns

  Prefer "chairperson" over "chairman"

• Gender Identity

  Prefer "transgender" over "transexual"

• Disability

  Prefer "autistic" over "aspie"

• Age

  Prefer "person born betwen 1946-1964" over "boomer"

• Race

  Prefer "primary-secondary" over "master-slave"

• Social Class

  Prefer "sex worker" over "prostitute"

• Violence Prefer "situation room" over "war room"

Advanced Edits POST

Request Parameters

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

HTTP method: POST

The Advanced Edits API POST endpoint takes JSON parameters documented below:

key: String
32-character API key.

text: String
Text to compute statistics for.

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

advanced_edits: Dictionary

Advanced Edit Options

Options for advanced edits. Option keys are String, and option values are Boolean.

• advanced_edits: Group setting, covering all the options below

• adverbs

• simplifications

• hard_to_read

• qualifiers

• voice

• dei: Group setting, covering all DEI options below

• gender: Group setting, covering gender_pronoun, gender_noun, and gender_id

• gender_pronoun

• gender_noun

• gender_id

• sensitivity

• disability

• age

• race

• social_class

• violence

A group setting marked false will disable all categories it covers.

Response Parameters

The Edits endpoint with advanced_edits specified returns JSON in the format of regular edits link.

Sample Code

cURL

curl -X POST https://api.sapling.ai/api/v1/edits \
     -H "Content-Type: application/json" \
     -d '{
        "key":"<api-key>",
        "text":"The ball was kicked. Suddenly there was the sound of an aircraft.",
        "session_id": "test session",
        "advanced_edits": { "advanced_edits": true }
    }'

JavaScript

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/edits',
            {
                key: '<api-key>',
                session_id: 'test session',
                text,
                advanced_edits: {
                    advanced_edits: true,
                },
            },
        );
        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('The ball was kicked. Suddenly there was the sound of an aircraft.');

Python

import requests
from pprint import pprint

key = '<api-key>'
url = 'https://api.sapling.ai/api/v1/edits'

data = {
    'key': key,
    'text': 'The ball was kicked. Suddenly there was the sound of an aircraft.',
    'session_id': 'Test Document UUID',
    'advanced_edits': {
        'advanced_edits': True,
    },
}

try:
    response = requests.post(url, json=data)
    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)

Sample Response

[
    {
        "description": "Reduce the use of passive voice.",
        "end": 19,
        "error_type": "voice",
        "general_error_type": "Advanced Edit",
        "id": "81695ccc-2916-50ba-8b93-c3ed7bb55f54",
        "replacement": "",
        "sentence": "The ball was kicked.",
        "sentence_start": 0,
        "start": 9
    },
    {
        "description": "Reduce the use of adverbs.",
        "end": 8,
        "error_type": "adverbs",
        "general_error_type": "Advanced Edit",
        "id": "62cb63df-7c3d-52de-aab2-eded6924d689",
        "replacement": "",
        "sentence": "Suddenly there was the sound of an aircraft.",
        "sentence_start": 21,
        "start": 0
    },
    {
        "description": "Use simpler language where possible.",
        "end": 43,
        "error_type": "simplifications",
        "general_error_type": "Advanced Edit",
        "id": "a0367693-de21-524f-9a3e-abe7a62b46f6",
        "replacement": "plane",
        "sentence": "Suddenly there was the sound of an aircraft.",
        "sentence_start": 21,
        "start": 35
    }
]