Skip to main content

API Access

See More

Anyone can test out Sapling's API. To get started with the API, simply:

  1. Register for a Sapling account here.
  2. Once you've registered and signed in, visit your Sapling API settings dashboard.
  3. Click the Generate Key button under the "API" section of the settings pane.
  4. Start using the API by following the API documentation. We recommend starting with the Edits Overview guide.

When making requests, you can authenticate by including your API key as a key parameter or by providing it as a bearer token in the Authorization header. If both are supplied, the key parameter takes precedence.

Prepaid API credits​

You can purchase prepaid API credits from the Billing section of the API settings dashboard. One credit equals one US dollar, and API usage draws down the balance using the same per-character prices described on the API pricing page.

The dashboard shows purchased, consumed, and remaining credits. Sapling sends a low-balance warning after the account reaches its configured consumption threshold. A positive prepaid balance can activate or reactivate API access without a metered subscription; when the balance is depleted, API requests return 402 Payment Required until more credits are purchased.

Payment-required responses​

Authenticated API requests can return 402 Payment Required when the API key has expired, the associated subscription is inactive, the account has reached its monthly billing limit, or its prepaid credit balance is depleted.

These responses include a Retry-After: 3600 header, where the value is the number of seconds clients should wait before trying again. The header is listed in Access-Control-Expose-Headers, so cross-origin browser clients can read it. Because resolving a 402 usually requires renewing access or updating billing settings, clients should inspect the response's msg field and avoid retrying continuously while the account remains inactive.

The response body is JSON with a msg field describing the reason:

{
  "msg": "API credit balance depleted. Purchase more credits at https://sapling.ai/api_settings#billing."
}

Production Key

Trial development keys allow for processing of 50,000 characters every 24 hours. Subscribe for production access and usage-based pricing, or purchase prepaid API credits to activate production access without a metered subscription.