Skip to main content

API Access

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 Grammar Check API (Edits) guide.

The key starts a free trial that works as a sandbox: it is never charged, and almost every endpoint only reads the text you send. See Sandbox & Testing for the trial limits, zero-cost health checks, and the few calls that change stored state.

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.

A machine-readable OpenAPI 3.1 specification of the API is available at https://api.sapling.ai/openapi.json. Use it to import the API into Postman, generate a typed client in any language, or register Sapling endpoints as tools for an AI agent.

Team API keys​

Team administrators can create and rotate team-scoped API keys in their team's settings. If the team already has an active paid API key, an administrator who does not personally subscribe to the API can create a replacement key using the eligible paying account behind an existing active team key. If no eligible paying account exists, creating a key still requires paid API access.

API usage is charged to the account that owns the new key, which may differ from the administrator who created it. Check the billed account before sharing a team key or rotating production credentials.

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 once you have used the configured share (shown as alert_threshold_percent in Account Status) of the credits bought since the last warning, so a top-up after a warning starts a fresh count. 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.

If a card payment on your API invoice fails, Sapling can switch the account to prepaid credits only. Account Status then reports credits_only: true, and API requests are served only while you have a positive prepaid balance. Buy credits to keep using the API, and contact us once your card is fixed to go back to monthly billing.

Automatic credit top-ups​

In the Billing section of API settings, accounts with prepaid credits can optionally turn on Automatic top-up. Choose the balance threshold, the number of credits to add per top-up, and a monthly top-up limit. Review the terms and confirm the consent dialog before enabling it; automatic charges are not enabled by a credit purchase alone.

Credit purchases securely save the payment method with Stripe for possible future top-ups. If you already have a usable payment method on file, you may be able to enable top-ups without another purchase. After your balance falls below the chosen threshold, eligible top-ups are processed periodically rather than during the API request itself. Failed payments or a missing usable payment method can disable automatic top-ups; review the dashboard to update your settings or payment method. The monthly limit caps the credits added automatically, not manual credit purchases.

Monthly metered spend limit​

For monthly usage billing, the Spend limit control in the Billing section of API settings lets you choose when metered API access should be paused. Enter 0 for No limit (the default), or set a whole-dollar limit of at least $10. You can change or remove the limit later.

When metered usage reaches the limit, requests can return 402 Payment Required until the limit is raised or a new billing cycle begins. If your account uses prepaid credits followed by metered billing, the limit applies only to the metered charges after credits run out, not to prepaid credit purchases. Prepaid-only accounts do not have this metered spend-limit control; the automatic top-up limit separately caps automatic credit purchases.

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.

One 402 is temporary. When a free-trial account uses up its daily character allowance, the block clears at the next UTC midnight. That response's Retry-After header and a numeric retry_after body field both give the seconds until the reset. To check a key's state without making a billable call, including the exact reason it is blocked, use Account Status. See Rate Limits & Errors for every status code.

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.