Backend Documentation

Import the Sapling client with:

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

constructor(...)

Returns a Sapling HTTP API Client wrapper.

Request Parameters

apiKey: String
32-character API key

options: Optional Object

Supported option fields:

• timeout: Optional Integer
  Timeout for API call in seconds. Defaults to 120000 milliseconds.
• hostname: Optional String
  Hostname override for SDK and self-hosted deployments.
• pathname: Optional String
  Pathname override for SDK and self-hosted deployments as well as version requirements.

Custom mappings and custom filters

The server-side JavaScript client provides methods to manage the custom corrections and filters attached to an API key. Keep the API key in your backend, rather than embedding it in browser JavaScript.

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

const client = new Client(process.env.SAPLING_API_KEY);

// Suggest this capitalization whenever "sapling" is encountered.
const { data: rule } = await client.addCustomMapping("sapling", "Sapling", {
  description: "Product name capitalization",
  case_sensitive: true,
});

const { data: mappings } = await client.customMappings();
// mappings.custom_mappings contains the account's mapping rules.
await client.deleteCustomMapping(rule.id); // HTTP 204; empty body

// Suppress a particular correction (rather than forcing a replacement).
const { data: filter } = await client.addCustomFilter(
  "Patient", "The patient", { case_sensitive: true }
);
const { data: filters } = await client.customFilters();
// filters.custom_filters contains the account's filter rules.
await client.deleteCustomFilter(filter.id); // HTTP 204; empty body

Method	Description
customMappings()	List mapping rules for the account.
addCustomMapping(entry, mapping, options?)	Create a correction with optional description and case_sensitive (default true).
deleteCustomMapping(id)	Delete a mapping by its UUID.
customFilters()	List filters that suppress edits.
addCustomFilter(input, output, options?)	Create a filter with optional case_sensitive; either side can be "" to act as a wildcard, but not both.
deleteCustomFilter(id)	Delete a filter by its UUID.

These methods wrap the Custom Mappings and Custom Filters API. Mappings support sentence-boundary markers (^, $) and # number placeholders. A mapping's description is displayed alongside its suggestion. The API can return HTTP 400 for duplicate, invalid, or unauthorized rule operations; deleting a rule returns an empty HTTP 204 response. All six operations are unbilled.

Usage and quota reporting

The server-side JavaScript client in @saplingai/sapling-js 1.0.54 and later provides four unbilled reporting methods. Use a private API key on your server. All four accept an optional options object with start_days_back and end_days_back: non-negative integer offsets from today. Omitted values use each endpoint's own defaults.

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

const client = new Client(process.env.SAPLING_API_KEY);

const { data: usage } = await client.apiUsage({
  start_days_back: 30,
  end_days_back: 0,
});
console.log(usage.total_characters, usage.total_cost_usd, usage.by_endpoint);

const { data: endpoints } = await client.apiEndpointUsage({
  start_days_back: 7,
  end_days_back: 0,
  interval: "Daily",
});
console.log(endpoints.data);

const { data: quota } = await client.apiQuotaUsage({
  start_days_back: 7,
  end_days_back: 0,
});
console.log(quota.quota, quota.usage);

const { data: activity } = await client.apiUserActivity({
  start_days_back: 7,
  end_days_back: 0,
});
console.log(activity.edits_shown, activity.active_users);

Method	Returns
apiUsage(options?)	Total characters and list-price cost, broken down by masked API key, endpoint, day, and month. Also includes credit_balance_data for non-team-scoped keys.
apiEndpointUsage(options?)	Per-endpoint characters in data, bucketed by interval: "Daily" (default), "Weekly", or "Monthly".
apiQuotaUsage(options?)	Monthly quota (-1 means unlimited), window usage, and current-month accepts / ignores counts.
apiUserActivity(options?)	edits_shown, edits_accepted, edits_ignored, and active_users counts.

The client validates window offsets and the interval before sending the request. The API rejects invalid reporting windows, and windows over one year return HTTP 403. For apiUsage(), a team-scoped key reports team usage; a user key reports usage for that user. API keys are masked in results. See the API Reporting reference for the underlying endpoints, defaults, and complete response fields.

edits(...)

Request Parameters

text: String
Text to process for edits.

sessionId: Optional String
Unique name or UUID of document or portion of text that is being checked

options: Optional Object

Supported options fields:

• 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, will return field containing text with edits applied. Note: this argument does not support HTML.

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

• advancedEdits: Optional Object
  

  Supported advancedEdits fields:

  • advanced_edits
  • adverbs
  • simplifications
  • hard_to_read
  • qualifiers
  • voice
  • dei
  • gender
  • gender_pronoun
  • gender_noun
  • gender_id
  • sensitivity
  • disability
  • age
  • race
  • social_class
  • violence

Response Parameters

Promise, 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"
}

accept(...)

Use this method 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 method only once in total.

Request Parameters

editUUID:String (UUID)
ID of an Edit.

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

Response Parameters

null

reject(...)

Use this method 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 method only once in total.

Request Parameters

editUUID: String (UUID)
ID of an Edit.

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

Response Parameters

null