Sandbox & Testing

Sapling has no separate sandbox host. The sandbox is a free trial key used against the production API at https://api.sapling.ai, no credit card required.

Get a test key

1. Register for a Sapling account.
2. Open the API settings dashboard and click Generate Key.

The key starts a free trial:

	Free trial key
Cost	Free. No credit card.
Expiry	30 days after the key is generated.
Keys per account	One.
Per-endpoint allowance	50,000 characters every 24 hours, refilled continuously.
Monthly quota	250,000 characters per key.
Daily account allowance	Shared across all endpoints. It resets at UTC midnight.

When a limit is reached, the API returns 429 (endpoint allowance or monthly quota) or 402 (daily account allowance), and the JSON body explains why. See Rate Limits & Errors for status codes and wait times. Account Status shows exact daily allowance and how much is left (trial.daily_limit_chars and trial.chars_used_today).

The same key works for the REST API, the SDKs and the MCP server.

API checks

These calls are not billed; uUse them to test connectivity and credentials.

Call	Key	What it tells you
GET https://api.sapling.ai/api/v1/liveness	Not needed	The API is up. Returns {"msg": "alive"}.
GET https://api.sapling.ai/openapi.json	Not needed	The machine-readable OpenAPI spec of every documented endpoint.
GET https://api.sapling.ai/api/v1/account/status?key=<key>	Required	Whether the key can make billable calls, and if not, why and for how long. See Account Status.

curl https://api.sapling.ai/api/v1/version
curl "https://api.sapling.ai/api/v1/account/status?key=$SAPLING_API_KEY"

Calls that store/modify state

Every documented endpoint not listed here only reads the text you send and returns a result.

Operation	What it changes
POST / DELETE /api/v1/dictionary	The account's custom dictionary.
POST / DELETE /api/v1/custom_mapping	The account's custom mappings.
POST / DELETE /api/v1/custom_filter	The account's custom filters.
POST / DELETE /api/v1/styleguide/rulesets	Saved style-guide rule sets, for the account or, with a team key, the team.
POST /api/v1/edits/{edit_hash}/accept, /reject and POST /api/v1/complete/{completion_hash}/accept	Record feedback on a suggestion. It appears in usage reports.
POST /api/v1/semsearch/create and DELETE /api/v1/semsearch/<entry_id>	A team's semantic search entries. (The POST /api/v1/semsearch query is read-only.)
Team endpoints (/api/v1/team/...)	Real team members, dictionaries, mappings and snippets.

The dictionary, custom mappings and custom filters belong to the account that owns the key. Every key on that account and the Sapling dashboard share them, and they change the results of later Edits calls.

Test data

Request text is handled as described in Data Processing. A no-data-retention option is available: contact us to enable it.

Automated tests and agents

• Unit tests: mock Sapling's responses. The OpenAPI spec gives exact response schemas to build fixtures from.
• Integration tests: keep them few and short, since each call uses allowance. Run account/status first so a spent allowance fails fast with a clear reason, not an unexpected error.
• Retries: handle 429 and 402 as described in Rate Limits & Errors. A trial 402 can mean waiting until UTC midnight.
• Agents: every MCP server tool processes text and returns a result. None of them write to the dictionary, custom mappings, rule sets or team settings, so an agent can be given a trial key and explore freely.

Moving to production

Subscribe or buy prepaid API credits. Your existing key keeps working: its expiry is removed and its limits are raised to the production defaults, so you don't need to change any configuration.

After that, you can generate more than one key. Keep a separate key for staging or CI, and give each key a name in the API settings dashboard. Usage for each key is available in API usage reports.