{"components":{"headers":{"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"XRateLimitLimit":{"description":"Total capacity of the caller's rate-limit bucket.","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Tokens remaining in the caller's rate-limit bucket.","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Seconds until the bucket is full again (a delta, not an epoch timestamp).","schema":{"type":"integer"}}},"responses":{"BadGateway":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay."},"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\"."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The team_id option names a team that does not exist or that the API key's user is not a member of."},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A named resource in the request does not exist for the authenticated account \u2014 e.g. a `ruleset` naming a saved rule set that was never created, was deleted, or belongs to another account. Correct or create the name; retrying unchanged will not help."},"PayloadTooLarge":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"result":{"type":"string"}},"type":"object"}}},"description":"Request body over 4MB. Note the body uses `message` and `result` keys, not the usual `msg`. Applies to requests authenticated via the Authorization header; a body-key-only request over the limit fails authentication instead (401), because the key cannot be read from the oversized body."},"PaymentRequired":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the trial daily cap resets (next UTC midnight). Present only for the temporary trial-cap case.","type":"integer"}},"type":"object"}]}}},"description":"Payment required. Two distinct cases share this status. (1) A PERMANENT block \u2014 an expired API key or subscription, or exhausted quota/prepaid credits: renew or top up at https://sapling.ai/api_settings, as re-authenticating or retrying will not help; its `Retry-After` is a conservative backoff hint. (2) A TEMPORARY free-trial block \u2014 a trial-only key that hit its daily character cap: this clears on its own when the cap resets at the next UTC midnight, its `Retry-After` states that actual reset, and the body carries a matching numeric `retry_after` field (whose presence also distinguishes the two cases).","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"RateLimited":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the request would fit the bucket. Absent when it never can.","type":"number"}},"type":"object"}]}}},"description":"Rate limited. Wait retry_after seconds (also in the Retry-After header) and retry. If retry_after is absent, the request exceeds the bucket capacity and can never succeed unchanged.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or invalid API key or OAuth access token. (An EXPIRED key or subscription answers 402, not 401.)"},"UploadRateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many uploads in the last minute. No Retry-After or rate-limit headers are sent; back off and retry."}},"schemas":{"Error":{"properties":{"msg":{"description":"Human-readable error message.","type":"string"}},"required":["msg"],"type":"object"}},"securitySchemes":{"apiKeyQuery":{"description":"Sapling API key passed as the `key` query parameter, an alternative to the Authorization bearer header.","in":"query","name":"key","type":"apiKey"},"bearerAuth":{"description":"Sapling API key. Language-tool operations also accept an OAuth access token from the Sapling authorization server \u2014 see the oauth2 scheme. The key may instead be sent as a `key` field in the JSON body, which takes precedence when both are present.","scheme":"bearer","type":"http"},"oauth2":{"description":"OAuth 2.1 authorization code flow with PKCE (S256). Clients may register dynamically (RFC 7591) at https://api.sapling.ai/oauth/register; server metadata is at https://api.sapling.ai/.well-known/oauth-authorization-server. The access token is sent as an `Authorization: Bearer` header and is accepted only on the language-tool operations that advertise OAuth security. Other authenticated operations require an API key.","flows":{"authorizationCode":{"authorizationUrl":"https://api.sapling.ai/oauth/authorize","refreshUrl":"https://api.sapling.ai/oauth/token","scopes":{"offline_access":"Receive a refresh token so access survives the 24-hour access-token lifetime.","sapling:api":"Call the Sapling language-tool endpoints in this document on behalf of the user, billed to the API key they choose at consent."},"tokenUrl":"https://api.sapling.ai/oauth/token"}},"type":"oauth2"}}},"externalDocs":{"description":"API documentation","url":"https://sapling.ai/docs/api"},"info":{"contact":{"name":"Sapling AI","url":"https://sapling.ai"},"description":"Language AI endpoints for grammar checking, AI-content detection, rewriting, moderation, and text analysis.\n\n## Authentication\n\nEvery endpoint except the `service` health probes requires a Sapling API key, sent either as an `Authorization: Bearer <key>` header or as a `key` field in the JSON request body (GET/DELETE operations and file uploads take a `key` query parameter instead). When both are sent, the body or query `key` takes precedence. Create keys at https://sapling.ai/api_settings.\n\nAgents that cannot ask a user for an API key can instead obtain an OAuth access token (authorization code + PKCE S256, scope `sapling:api`) from the authorization server described by the `oauth2` security scheme, and send it as the `Authorization: Bearer` header. Such a token acts on the API key the user picks at consent and is accepted only on the language-tool operations that advertise OAuth security. Other authenticated operations require an API key. Discovery metadata: `/.well-known/oauth-protected-resource` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414).\n\n## Usage reporting\n\nEvery API-key operation accepts an optional `return_usage: true` request field (or `?return_usage=true` for GET/DELETE and file uploads). When set, a successful JSON-object response additionally carries `\"usage\": {\"characters\": <n>}` \u2014 the billable character count the request submitted (0 when nothing was billed; the 2.5x logographic-language adjustment is included, and the number is an upper bound on the final charge, since repeat texts inside the billing deduplication window are counted but not re-charged). Existing `usage` fields, including the account/status summary and completion token usage, are preserved.\n\n## Batch requests\n\nOperations whose request schema lists a `texts` property also accept a batch of 1 to 10 texts in one request: send exactly one of `text` or `texts`, and the response is `{\"results\": [...]}`, one single-text response per input text in input order.\n\n## Rate limiting\n\nToken-bucket rate-limited operations (those whose responses declare the headers below) carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers describing the caller's token bucket \u2014 unless the API key itself is configured as unthrottled, in which case no rate-limit headers are emitted. (A deployment that disables API burst limits emits none of them and no bucket 429s; the document it serves reflects that.) `X-RateLimit-Reset` is the number of SECONDS until the bucket is full again, not an epoch timestamp. 429 responses additionally carry `Retry-After` (seconds) and a numeric `retry_after` body field; when `retry_after` is absent from a 429 body, the request can never succeed at its current size, so do not retry it unchanged.\n\n## Errors\n\nErrors are JSON objects with a human-readable `msg` field and an appropriate HTTP status \u2014 including request-validation 400s, auth 401s, unknown paths (404), wrong methods (405), and unexpected 500s. Some operations use an `error` field or `message`/`result` keys instead of `msg` (including the 4MB 413 and invalid feedback IDs), and `/api/v1/edits` can answer a transient tokenizer outage with an empty JSON array and status 400. Treat the status code as authoritative and see each operation's response schemas for the exact shapes. 5xx/503 responses may carry `Retry-After`; honor it before retrying.\n\nThe language operations are generated from the same registry that backs the hosted MCP server (https://mcp.sapling.ai), so tool names and their operationIds match. OAuth access tokens issued for that server work only on those operations; every other operation needs an API key. Full response schemas and guides: https://sapling.ai/docs/api","termsOfService":"https://sapling.ai/terms","title":"Sapling AI API","version":"1.4.4"},"openapi":"3.1.0","paths":{"/api/v1/account/limits":{"get":{"description":"How much the presented key may send: its per-endpoint character bucket (capacity and refill window), monthly character quota, expiry, and for personal keys the account spend limit and free-trial daily cap. Unbilled, and works even when the key is blocked; pair it with GET /api/v1/account/status for the live verdict. The same handler is exposed on POST (sapling_account_limits_post).","externalDocs":{"url":"https://sapling.ai/docs/api/account-status/"},"operationId":"sapling_account_limits","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"key_expires_at":{"description":"ISO 8601 UTC time the key expires, or null."},"monthly_quota_chars":{"description":"Characters this key may send per calendar month (UTC), or null when the key has no quota."},"monthly_spend_limit_usd":{"description":"The account spend limit in US dollars per billing period, or null when none is set. Omitted for team keys."},"rate_limit":{"description":"Null for an unthrottled key. Otherwise {capacity_chars, window_seconds}: each endpoint draws on its own bucket of capacity_chars characters, refilled evenly over window_seconds. The X-RateLimit-* headers report the same bucket live. capacity_chars 0 means the key is disabled."},"trial":{"description":"Free-trial daily character cap. Present only for trial accounts on a personal key.","type":"object"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The configured limits of the presented key.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot query account limits. MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Read the rate limit, quota and spend limit of this API key","tags":["account"]},"post":{"description":"POST form of GET /api/v1/account/limits (sapling_account_limits), for clients that credential via a JSON `key` body. Identical behavior and response.","externalDocs":{"url":"https://sapling.ai/docs/api/account-status/"},"operationId":"sapling_account_limits_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"key_expires_at":{"description":"ISO 8601 UTC time the key expires, or null."},"monthly_quota_chars":{"description":"Characters this key may send per calendar month (UTC), or null when the key has no quota."},"monthly_spend_limit_usd":{"description":"The account spend limit in US dollars per billing period, or null when none is set. Omitted for team keys."},"rate_limit":{"description":"Null for an unthrottled key. Otherwise {capacity_chars, window_seconds}: each endpoint draws on its own bucket of capacity_chars characters, refilled evenly over window_seconds. The X-RateLimit-* headers report the same bucket live. capacity_chars 0 means the key is disabled."},"trial":{"description":"Free-trial daily character cap. Present only for trial accounts on a personal key.","type":"object"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The configured limits of the presented key.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot query account limits. MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Read the rate limit, quota and spend limit of this API key","tags":["account"]}},"/api/v1/account/status":{"get":{"description":"One-call self-diagnosis for the presented key: whether billable endpoints will serve it, and if not why (`blocked_reason`) and for how long (`retry_after`). Works even when the key is blocked. The same handler is exposed on POST (sapling_account_status_post). Team-scoped keys receive only the verdict and their own quota.","externalDocs":{"url":"https://sapling.ai/docs/api/account-status/"},"operationId":"sapling_account_status","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"api_access":{"type":"boolean"},"blocked_reason":{"description":"Null when api_access is true, else one of key_expired, credits_depleted, subscription_expired, trial_daily_limit, monthly_billing_limit, monthly_quota_exhausted."},"credits":{"type":"object"},"message":{"description":"Human-readable reason, or null."},"retry_after":{"description":"Seconds until the block may clear. Present only when blocked.","type":"integer"},"subscription":{"type":"object"},"trial":{"type":"object"},"usage":{"type":"object"}},"type":"object"}}},"description":"Access verdict plus credit, subscription, usage and trial details.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot query account status. MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Check whether this API key can make billable calls","tags":["account"]},"post":{"description":"POST form of GET /api/v1/account/status (sapling_account_status), for clients that credential via a JSON `key` body. Identical behavior and response.","externalDocs":{"url":"https://sapling.ai/docs/api/account-status/"},"operationId":"sapling_account_status_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"api_access":{"type":"boolean"},"blocked_reason":{"description":"Null when api_access is true, else one of key_expired, credits_depleted, subscription_expired, trial_daily_limit, monthly_billing_limit, monthly_quota_exhausted."},"credits":{"type":"object"},"message":{"description":"Human-readable reason, or null."},"retry_after":{"description":"Seconds until the block may clear. Present only when blocked.","type":"integer"},"subscription":{"type":"object"},"trial":{"type":"object"},"usage":{"type":"object"}},"type":"object"}}},"description":"Access verdict plus credit, subscription, usage and trial details.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot query account status. MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Check whether this API key can make billable calls","tags":["account"]}},"/api/v1/aidetect":{"post":{"description":"Score how likely a text is to be AI-generated. Returns an overall score between 0 (likely human-written) and 1 (likely AI-generated), ai_fraction (the share of the text in sentences scoring >= 0.5, which flags partially AI-written documents), a verdict (human, mixed or ai), segments (character offsets of the AI-scored passages), low_confidence with low_confidence_reasons (short_text, list_format: inputs where false positives are more likely, so hedge the result), plus per-sentence scores by default. Provide at least ~50 characters of text for a meaningful score; 500+ characters of prose is most reliable. English, Arabic, Chinese, Dutch, French, German, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swedish and Turkish are supported: the language is detected automatically (or set it with lang), text in the non-English languages is scored by a multilingual model, and the response's version field names the model that scored the text. Other languages are scored by the English model and are less reliable.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_ai_detect","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"create_report":{"default":false,"description":"Also save the result as a shareable report and return its link in report (a single text only, not texts). The report is saved to your AI detector history, where you can revoke the link; anyone with the link can view the text and its scores until it is revoked or expires 90 days after creation. Requires your private API key: OAuth access tokens and public API keys get 400, as does combining it with zero_retention. No report is made (report is null, see report_skip_reason) when your team keeps no data, AI detector history or text retention is turned off, or the account email is unconfirmed; the request is still scored and billed.","type":"boolean"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"Language of the text: en, ar, de, es, fr, it, ja, ko, nl, pl, pt, ro, ru, sv, tr or zh. Omit (or \"auto\") to detect it; other languages are rejected.","type":"string"},"min_words":{"description":"Abstain on out-of-scope input (off by default). When set, text with fewer words than this (Chinese/Japanese: ~2 characters per word) or mostly bullet/numbered lines gets verdict \"insufficient_text\" instead of a judgement, with insufficient_text_reasons (below_min_words, list_format); score is still returned. 50 matches the common 50-word floor for reliable detection.","maximum":1000,"minimum":1,"type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"sent_scores":{"description":"Include per-sentence scores (default true).","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit. Requires your own API key; the public demo key is limited to the single `text` form.","items":{"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"zero_retention":{"description":"Keep no copy of the text: the result is not cached (so no certificate hash), and usage is logged without the text. Default false; always on for teams with data retention disabled.","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"report":{"description":"The shareable report for this result (create_report: true), or null when none was made.","properties":{"expires_at":{"description":"When the link stops resolving unless revoked or deleted sooner.","format":"date-time","type":"string"},"id":{"description":"AI detector history entry id.","type":"string"},"shared_at":{"format":"date-time","type":"string"},"url":{"description":"Public report link.","type":"string"}}},"report_skip_reason":{"description":"Why report is null: nonpersist (team keeps no data), disabled (AI detector history off), text_not_retained (history keeps no text), unconfirmed_email, quota (history full), unscorable, error.","enum":["nonpersist","disabled","text_not_retained","unconfirmed_email","quota","unscorable","error"],"type":"string"},"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"properties":{"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"}},"type":"object"},"type":"array"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/detector/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"AI-generated text detection","tags":["detection"]}},"/api/v1/aidetect/bulk":{"post":{"description":"Queue up to 1,000 texts (1,000,000 characters combined, 200,000 per text) for asynchronous scoring. Each item is scored and billed exactly like the same text sent to /api/v1/aidetect. Poll GET /api/v1/aidetect/bulk/{bulk_id}, then page through its results; jobs are kept 48 hours after they finish. Each text is stored until it is scored, so zero_retention: true, or an account on a team that does not persist data, is refused with a 400.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_bulk_submit","requestBody":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"id":{"description":"Your id for the item, echoed in results.","maxLength":128,"type":"string"},"text":{"maxLength":200000,"type":"string"}},"required":["text"],"type":"object"},"maxItems":1000,"minItems":1,"type":"array"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"sent_scores":{"default":false,"type":"boolean"},"version":{"type":"string"},"zero_retention":{"default":false,"description":"Not supported for bulk jobs: true is refused with a 400.","type":"boolean"}},"required":["items"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"bulk_id":{"format":"uuid","type":"string"},"completed_at":{"description":"Unix seconds; null until the job finishes."},"created_at":{"description":"Unix seconds.","type":"integer"},"expires_at":{"description":"Unix seconds; results are deleted then.","type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"status":{"enum":["queued","running","succeeded","failed","partial"],"type":"string"},"succeeded":{"type":"integer"},"total_chars":{"type":"integer"},"total_items":{"type":"integer"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Job accepted.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Submit a bulk AI-detection job","tags":["detection"]}},"/api/v1/aidetect/bulk/{bulk_id}":{"get":{"description":"Status and counters of a job this key (or, for a personal key, its account) submitted. Works even when the key is blocked from billable calls (no 402).","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_bulk_status","parameters":[{"description":"The `bulk_id` from the submit call.","in":"path","name":"bulk_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"bulk_id":{"format":"uuid","type":"string"},"completed_at":{"description":"Unix seconds; null until the job finishes."},"created_at":{"description":"Unix seconds.","type":"integer"},"expires_at":{"description":"Unix seconds; results are deleted then.","type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"status":{"enum":["queued","running","succeeded","failed","partial"],"type":"string"},"succeeded":{"type":"integer"},"total_chars":{"type":"integer"},"total_items":{"type":"integer"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Job status.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A named resource in the request does not exist for the authenticated account \u2014 e.g. a `ruleset` naming a saved rule set that was never created, was deleted, or belongs to another account. Correct or create the name; retrying unchanged will not help.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Bulk AI-detection job status","tags":["detection"]}},"/api/v1/aidetect/bulk/{bulk_id}/results":{"get":{"description":"One page of per-item results in submission order. Items not scored yet have status `queued` and a null result; failed items carry `error`. Works even when the key is blocked from billable calls (no 402).","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_bulk_results","parameters":[{"description":"The `bulk_id` from the submit call.","in":"path","name":"bulk_id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"First item index to return.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}},{"description":"Items per page.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":1000,"minimum":1,"type":"integer"}},{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"bulk_id":{"format":"uuid","type":"string"},"items":{"items":{"properties":{"error":{"description":"Failure message (string); null unless failed."},"id":{"description":"Your item id (string), or null when none was sent."},"index":{"type":"integer"},"result":{"description":"The /api/v1/aidetect single-text response (object), without tokens/token_probs; null unless succeeded."},"status":{"enum":["queued","succeeded","failed"],"type":"string"}},"type":"object"},"type":"array"},"limit":{"type":"integer"},"offset":{"type":"integer"},"status":{"enum":["queued","running","succeeded","failed","partial"],"type":"string"},"total_items":{"type":"integer"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"One page of results.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A named resource in the request does not exist for the authenticated account \u2014 e.g. a `ruleset` naming a saved rule set that was never created, was deleted, or belongs to another account. Correct or create the name; retrying unchanged will not help.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Bulk AI-detection job results","tags":["detection"]}},"/api/v1/aidetect/models":{"get":{"description":"The detector `version` values this deployment serves: `default` scores unpinned text, `routes` maps each routed language to its model, and `models` lists every version with its family, languages, release date and status (`default`, `routed`, or `pinned` = served only when a request sends that `version`). No API key needed; not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_ai_detect_models","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"default":{"description":"Version that scores unpinned text; null while a rollout leaves unpinned requests on a mixed-version pool."},"models":{"items":{"properties":{"family":{"enum":["english","multilingual"],"type":"string"},"languages":{"description":"Languages the model was built for; empty when not yet known.","items":{"type":"string"},"type":"array"},"pinnable":{"description":"Whether a request may send this version as `version`. False for a routed model not yet available as an explicit pin.","type":"boolean"},"released":{"description":"Omitted when the version has no date suffix.","format":"date","type":"string"},"routed_languages":{"items":{"type":"string"},"type":"array"},"status":{"enum":["default","routed","pinned"],"type":"string"},"version":{"type":"string"}},"type":"object"},"type":"array"},"routes":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"description":"Model catalog."}},"security":[],"summary":"List AI detector model versions","tags":["detection"]}},"/api/v1/classify":{"post":{"description":"Classify a text into a set of labels you supply \u2014 intent, topic, category, routing queue, sentiment buckets, anything \u2014 without training data. Returns label (the best match, always one of your labels), labels (single-label: just the best match; multi-label: every label whose score >= threshold, possibly empty), scores (one {label, score} per input label, descending; a distribution in single-label mode, independent 0-1 applicability in multi-label mode) and a one-sentence rationale. Labels can be plain names or {name, description} objects \u2014 a short description per label sharpens borderline decisions. Use context to say what the texts are (e.g. \"support tickets for a billing product\"). 2-20 labels.","externalDocs":{"url":"https://sapling.ai/docs/api/classify/"},"operationId":"sapling_classify","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"context":{"description":"Optional guidance (max 500 chars): what the texts are and how to decide borderline cases.","maxLength":500,"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"labels":{"description":"The candidate labels (2-20): label names (<=50 chars), or {name, description (<=200 chars)} objects. Names must be unique.","items":{"anyOf":[{"maxLength":50,"minLength":1,"type":"string"},{"additionalProperties":false,"properties":{"description":{"maxLength":200,"type":"string"},"name":{"maxLength":50,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}]},"maxItems":20,"minItems":2,"type":"array"},"multi_label":{"description":"true = several labels may apply at once (labels = those scoring >= threshold). Default false = exactly one label.","type":"boolean"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","maxLength":10000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":10000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"threshold":{"description":"Multi-label cut-off on the per-label score (default 0.5). Ignored in single-label mode.","maximum":1,"minimum":0,"type":"number"}},"required":["labels"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/classify/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Zero-shot text classification","tags":["analysis"]}},"/api/v1/complete":{"post":{"description":"Predict how a partially written sentence continues. Send the trailing text the user has typed as query (200 characters maximum) and the tool returns the predicted continuation. Requires an API key with autocomplete enabled; other keys get an explicit error back.","externalDocs":{"url":"https://sapling.ai/docs/api/autocomplete/"},"operationId":"sapling_autocomplete","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"query":{"description":"The partial text to continue, at most 200 characters. Send the end of what the user has typed, not the whole document.","maxLength":200,"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional stable identifier for the document or conversation being written.","type":"string"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"},{"type":"array"}]}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/autocomplete/ An empty JSON array is returned when no completion is available (prediction failed or was shorter than the minimum length).","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Autocomplete a sentence","tags":["generation"]}},"/api/v1/complete/{completion_hash}/accept":{"post":{"description":"Report that the user accepted an autocomplete suggestion. `context` must be exactly the `{query, completion}` object the completion hash was computed from \u2014 extra keys fail the hash check.","externalDocs":{"url":"https://sapling.ai/docs/api/autocomplete/"},"operationId":"sapling_accept_completion","parameters":[{"description":"The `hash` returned by /api/v1/complete.","in":"path","name":"completion_hash","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"context":{"properties":{"completion":{"type":"string"},"query":{"type":"string"}},"required":["query","completion"],"type":"object"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional session identifier used to group feedback events.","type":"string"}},"required":["context"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"result":{"enum":["success"],"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Recorded."},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"message":{"type":"string"},"result":{"type":"string"}},"type":"object"}]}}},"description":"Invalid request. A malformed id answers {\"message\": ..., \"result\": \"failure\"}; a missing or mismatched context answers the {\"msg\": ...} Error shape, as do malformed JSON or missing arguments. Handle both shapes."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Record an accepted completion","tags":["generation"]}},"/api/v1/custom_filter":{"get":{"description":"Rules that suppress a specific suggestion (input -> output) from /api/v1/edits.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_list_custom_filters","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"custom_filters":{"items":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"id":{"format":"uuid","type":"string"},"input":{"type":"string"},"output":{"type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Custom filters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List custom filters","tags":["proofreading"]},"post":{"description":"Suppress suggestions that change `inp` into `out`. Note the request keys are `inp`/`out` while responses use `input`/`output`.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_add_custom_filter","requestBody":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"default":true,"description":"Whether matching is case sensitive. Defaults to true.","type":"boolean"},"inp":{"description":"Original text of the suggestion.","type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"out":{"description":"Replacement to suppress.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"id":{"format":"uuid","type":"string"},"input":{"type":"string"},"output":{"type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The created filter."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request: both inp and out blank, inp equal to out, duplicate rule, more than two digits in inp, or a rule that must be marked case sensitive."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Add a custom filter","tags":["proofreading"]}},"/api/v1/custom_filter/{filter_id}":{"delete":{"description":"Remove a filter by the `id` returned when listing or adding it.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_delete_custom_filter","parameters":[{"description":"Custom filter id.","in":"path","name":"filter_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"204":{"description":"Deleted. Empty body."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The id is malformed, or no entry with this id belongs to the authenticated account (this endpoint answers 400, not 404)."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Delete a custom filter","tags":["proofreading"]}},"/api/v1/custom_mapping":{"get":{"description":"Custom replacement rules (entry -> mapping) applied as suggestions by /api/v1/edits.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_list_custom_mappings","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"custom_mappings":{"items":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"description":{"description":"Shown to the user with the suggestion; null when none was set."},"entry":{"type":"string"},"id":{"format":"uuid","type":"string"},"mapping":{"type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Custom mappings."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List custom mappings","tags":["proofreading"]},"post":{"description":"Suggest `mapping` whenever `entry` appears in checked text.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_add_custom_mapping","requestBody":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"default":true,"description":"Whether matching is case sensitive. Defaults to true.","type":"boolean"},"description":{"default":"","description":"Shown to the user with the suggestion.","type":"string"},"entry":{"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"mapping":{"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["entry","mapping"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"description":{"description":"Shown to the user with the suggestion; null when none was set."},"entry":{"type":"string"},"id":{"format":"uuid","type":"string"},"mapping":{"type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The created mapping."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request, duplicate rule, entry equal to mapping, an entry with more than two digits, or a rule that must be marked case sensitive."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Add a custom mapping","tags":["proofreading"]}},"/api/v1/custom_mapping/{mapping_id}":{"delete":{"description":"Remove a mapping by the `id` returned when listing or adding it.","externalDocs":{"url":"https://sapling.ai/docs/api/custom-mappings/"},"operationId":"sapling_delete_custom_mapping","parameters":[{"description":"Custom mapping id.","in":"path","name":"mapping_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"204":{"description":"Deleted. Empty body."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The id is malformed, or no entry with this id belongs to the authenticated account (this endpoint answers 400, not 404)."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Delete a custom mapping","tags":["proofreading"]}},"/api/v1/dictionary":{"get":{"description":"Words the grammar and spelling checkers accept as correct for this account. Returns a bare JSON array sorted by entry.","externalDocs":{"url":"https://sapling.ai/docs/api/dictionary/"},"operationId":"sapling_list_dictionary","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"entry":{"type":"string"},"id":{"format":"uuid","type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"}},"type":"object"},"type":"array"}}},"description":"Dictionary entries."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List custom dictionary entries","tags":["proofreading"]},"post":{"description":"Add a word the grammar and spelling checkers should accept.","externalDocs":{"url":"https://sapling.ai/docs/api/dictionary/"},"operationId":"sapling_add_dictionary_entry","requestBody":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"default":true,"description":"Whether matching is case sensitive. Defaults to true.","type":"boolean"},"entry":{"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["entry"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"case_sensitive":{"type":"boolean"},"created_at":{"description":"RFC 1123 timestamp, e.g. \"Wed, 07 Oct 2020 21:15:47 GMT\".","type":"string"},"entry":{"type":"string"},"id":{"format":"uuid","type":"string"},"updated_at":{"description":"RFC 1123 timestamp.","type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The created entry."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request, duplicate entry (\"Entry already exists.\"), or an entry with more than two digits."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Add a custom dictionary entry","tags":["proofreading"]}},"/api/v1/dictionary/{entry_id}":{"delete":{"description":"Remove an entry by the `id` returned when listing or adding it.","externalDocs":{"url":"https://sapling.ai/docs/api/dictionary/"},"operationId":"sapling_delete_dictionary_entry","parameters":[{"description":"Dictionary entry id.","in":"path","name":"entry_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"204":{"description":"Deleted. Empty body."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The id is malformed, or no entry with this id belongs to the authenticated account (this endpoint answers 400, not 404)."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"Delete a custom dictionary entry","tags":["proofreading"]}},"/api/v1/docx-aidetect":{"post":{"description":"Upload a .docx; its extracted text (first 200,000 characters) is scored like /api/v1/aidetect with sentence scores. Billed like /api/v1/aidetect.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_docx","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional part carrying a JSON object, e.g. {\"key\": \"<API key>\", \"return_usage\": true}, as an alternative to the query or header credential. Send it as a file part.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ai_fraction":{"description":"Share (0-1) of the text in sentences scoring >= 0.5; reports partially AI-written documents whose overall score stays below 0.5.","type":"number"},"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"score":{"type":"number"},"score_string":{"type":"string"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"sentence_scores":{"items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"sentence":{"type":"string"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Same shape as /api/v1/aidetect with sent_scores and score_string enabled."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"Missing `file` part, unsupported extension, or the document could not be read (empty, encrypted, corrupt, or no extractable text). Body: {\"error\": \"<reason>\"}. A request with no API key at all also answers 400 {\"error\": \"Unauthenticated\"}. A transient scoring failure also answers 400 {\"error\": \"Unexpected error\"}; that case is safe to retry after a short delay."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"$ref":"#/components/responses/UploadRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Detect AI-generated text in a Word document","tags":["detection"]}},"/api/v1/edits":{"post":{"description":"Check text for grammar, spelling, and style issues. Returns a list of suggested edits, each with the sentence, character span (start/end), replacement text, and an error type. Set auto_apply=true to also receive applied_text: the input with all suggested edits already applied (useful to return a corrected document in one call). Set include_error_categories=false to skip error classification and get only the corrections and offsets back (faster and lighter when you only need to apply fixes). Supports many languages via the lang parameter. If the result carries a degraded object it is partial: some sentences may be missing some or all of their corrections (the edits returned are still valid); call again for a complete result.","externalDocs":{"url":"https://sapling.ai/docs/api/edits-overview/"},"operationId":"sapling_grammar_check","requestBody":{"content":{"application/json":{"schema":{"properties":{"auto_apply":{"description":"If true, the response includes applied_text with all edits applied to the input.","type":"boolean"},"include_error_categories":{"description":"Defaults to true. If false, edits omit error_type, general_error_type and classifier-generated descriptions; corrections, offsets, IDs and applied_text are unchanged.","type":"boolean"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"ISO 639-1 language code of the text (e.g. \"en\", \"de\", \"fr\"). Defaults to \"en\".","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional stable identifier for the document or conversation being checked. Reuse the same value when re-checking the same document.","type":"string"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"variety":{"description":"English variety to enforce, e.g. \"us-variety\" or \"gb-variety\". Optional.","enum":["us-variety","gb-variety","au-variety","ca-variety","s-variety","t-variety","null-variety"],"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"degraded":{"description":"Present only on a partial result: a model stage could not process some sentences in time, so those sentences may be missing some or all of their corrections (a failed primary stage leaves a sentence unchecked; a failed secondary stage, e.g. neural spellcheck or postprocessing, drops only that stage's corrections). Every edit returned is still valid. Absent from a fully successful response. Retry the request (after a short backoff) for a complete result.","properties":{"reason":{"enum":["model_timeout","model_unavailable","model_error"],"type":"string"},"sentences_degraded":{"minimum":1,"type":"integer"},"sentences_total":{"minimum":1,"type":"integer"}},"required":["sentences_degraded","sentences_total","reason"],"type":"object"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"},{"type":"array"}]}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/edits-overview/ With noformat=true (the SDK response shape) the body is a bare array of edit objects instead. A partial result (some corrections may be missing) adds a `degraded` object; retry for a complete result.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"array"}]}}},"description":"Invalid request, as for the other endpoints \u2014 but this operation also answers a sentence-tokenization outage with an empty JSON array body and status 400. That array case is a TRANSIENT upstream failure, not a caller error, and is safe to retry after a short delay. Treat the status code as authoritative and tolerate both body shapes.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The team_id option names a team that does not exist or that the API key's user is not a member of.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Grammar and spelling check","tags":["proofreading"]}},"/api/v1/edits/{edit_hash}/accept":{"post":{"description":"Report that the user accepted a suggestion returned by /api/v1/edits or /api/v1/spellcheck. Feedback improves the suggestions shown to that user. The body must be a non-empty JSON object; include `user_id` or the feedback is not recorded.","externalDocs":{"url":"https://sapling.ai/docs/api/edits-overview/"},"operationId":"sapling_accept_edit","parameters":[{"description":"The edit's `id` from /edits.","in":"path","name":"edit_hash","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional session identifier used to group feedback events.","type":"string"},"user_id":{"description":"Your identifier for the end user. The feedback is acknowledged but NOT recorded when omitted.","maxLength":100,"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"result":{"enum":["success"],"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Acknowledged."},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"message":{"type":"string"},"result":{"type":"string"}},"type":"object"}]}}},"description":"Invalid request. A malformed id answers {\"message\": ..., \"result\": \"failure\"}; a missing or mismatched context answers the {\"msg\": ...} Error shape, as do malformed JSON or missing arguments. Handle both shapes."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Record an accepted edit","tags":["proofreading"]}},"/api/v1/edits/{edit_hash}/reject":{"post":{"description":"Report that the user rejected a suggestion returned by /api/v1/edits or /api/v1/spellcheck; similar suggestions are then suppressed for that user. The body must be a non-empty JSON object; include `user_id` or the feedback is not recorded.","externalDocs":{"url":"https://sapling.ai/docs/api/edits-overview/"},"operationId":"sapling_reject_edit","parameters":[{"description":"The edit's `id` from /edits.","in":"path","name":"edit_hash","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional session identifier used to group feedback events.","type":"string"},"user_id":{"description":"Your identifier for the end user. The feedback is acknowledged but NOT recorded when omitted.","maxLength":100,"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"result":{"enum":["success"],"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Acknowledged."},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"message":{"type":"string"},"result":{"type":"string"}},"type":"object"}]}}},"description":"Invalid request. A malformed id answers {\"message\": ..., \"result\": \"failure\"}; a missing or mismatched context answers the {\"msg\": ...} Error shape, as do malformed JSON or missing arguments. Handle both shapes."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Record a rejected edit","tags":["proofreading"]}},"/api/v1/extract":{"post":{"description":"Pull structured fields out of unstructured text \u2014 invoice numbers, amounts, dates, names, addresses, order ids, anything the document actually states \u2014 by describing the fields you want. Returns data (a {field: value} map, null where the text does not state the field), fields (per-field value, the verbatim evidence span it came from, and whether it was found) and missing (the fields the text did not yield). Values are returned in the type you declare (string, number, integer, boolean, date as YYYY-MM-DD, or list of strings) and a value that will not convert is reported missing rather than returned in the wrong type. This is EXTRACTION, not summarization or inference: except for boolean fields, a value must be traceable to a span of the text or it is dropped. Use context to say what the document is. 1-20 fields.","externalDocs":{"url":"https://sapling.ai/docs/api/extract/"},"operationId":"sapling_extract","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"context":{"description":"Optional guidance (max 500 chars): what the document is and how to read ambiguous fields.","maxLength":500,"type":"string"},"fields":{"description":"The fields to extract (1-20): field names (<=50 chars), or {name, type, description (<=200 chars), required} objects. A short description per field sharpens ambiguous ones. Names must be unique.","items":{"anyOf":[{"maxLength":50,"minLength":1,"type":"string"},{"additionalProperties":false,"properties":{"description":{"maxLength":200,"type":"string"},"name":{"maxLength":50,"minLength":1,"type":"string"},"required":{"description":"Hint that the field should be present; it is still reported missing rather than guessed.","type":"boolean"},"type":{"description":"Value type (default string). \"date\" is returned as YYYY-MM-DD; \"list\" is a list of strings.","enum":["string","number","integer","boolean","date","list"],"type":"string"}},"required":["name"],"type":"object"}]},"maxItems":20,"minItems":1,"type":"array"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","maxLength":10000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":10000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"required":["fields"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/extract/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Structured data extraction","tags":["analysis"]}},"/api/v1/file-aidetect":{"post":{"description":"Upload a document (.pdf, .docx, .pptx, .odt, .txt, .md, .html or .htm, chosen by file extension, up to 30MB); its extracted text (first 200,000 characters) is scored like /api/v1/aidetect with sentence scores. PPTX text is read in slide order without speaker notes; ODT drops footnotes, comments and tracked deletions; HTML is flattened to its visible text. Billed like /api/v1/aidetect.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_file","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional JSON object (send it as a file part or form field): {\"zero_retention\": true} keeps no copy of the extracted text (no result cache or certificate hash, usage logged without text), as on /api/v1/aidetect; {\"create_report\": true} also saves the result as a shareable report and adds report (and report_skip_reason when none was made), as on /api/v1/aidetect.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ai_fraction":{"description":"Share (0-1) of the text in sentences scoring >= 0.5; reports partially AI-written documents whose overall score stays below 0.5.","type":"number"},"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"report":{"description":"The shareable report for this result (create_report: true), or null when none was made.","properties":{"expires_at":{"description":"When the link stops resolving unless revoked or deleted sooner.","format":"date-time","type":"string"},"id":{"description":"AI detector history entry id.","type":"string"},"shared_at":{"format":"date-time","type":"string"},"url":{"description":"Public report link.","type":"string"}}},"report_skip_reason":{"description":"Why report is null: nonpersist (team keeps no data), disabled (AI detector history off), text_not_retained (history keeps no text), unconfirmed_email, quota (history full), unscorable, error.","enum":["nonpersist","disabled","text_not_retained","unconfirmed_email","quota","unscorable","error"],"type":"string"},"score":{"type":"number"},"score_string":{"type":"string"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"sentence_scores":{"items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"sentence":{"type":"string"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Same shape as /api/v1/aidetect with sent_scores and score_string enabled."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"Missing `file` part, unsupported extension, or the document could not be read (empty, encrypted, corrupt, or no extractable text). Body: {\"error\": \"<reason>\"}. A request with no API key at all also answers 400 {\"error\": \"Unauthenticated\"}. A transient scoring failure also answers 400 {\"error\": \"Unexpected error\"}; that case is safe to retry after a short delay. A non-boolean zero_retention or create_report, or create_report with zero_retention or without a private API key, answers 400 {\"error\": \"<reason>\"}."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"$ref":"#/components/responses/UploadRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Detect AI-generated text in an uploaded document","tags":["detection"]}},"/api/v1/file-extract":{"post":{"description":"Upload a document (.pdf, .docx, .pptx, .odt, .txt, .md, .html or .htm, up to 30MB) and extract caller-named fields from its text exactly like /api/v1/extract. Options ride the jsonParams part. Text past the first 10,000 characters is not read; the response `document` object reports `truncated`. Billed like /api/v1/extract on the characters used. Unbilled (trial and public) keys also answer 429 with Retry-After when their per-minute generation budget is spent.","externalDocs":{"url":"https://sapling.ai/docs/api/extract/"},"operationId":"sapling_extract_file","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"JSON object (send it as a file part or form field): {\"fields\": [...], \"context\": \"...\", \"key\": \"<API key>\", \"return_usage\": true}. `fields` (required) and `context` take the same values as on /api/v1/extract.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file","jsonParams"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"document":{"properties":{"characters":{"description":"Characters of text extracted from the file.","type":"integer"},"characters_used":{"description":"Characters read for extraction (and billed).","type":"integer"},"file_type":{"type":"string"},"truncated":{"type":"boolean"}},"type":"object"},"fields":{"items":{"type":"object"},"type":"array"},"missing":{"items":{"type":"string"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Same shape as a single /api/v1/extract response, plus `document`."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"msg":{"type":"string"}},"type":"object"}}},"description":"Missing/unsupported file, unreadable document, no text ({\"error\": \"<reason>\"}), or invalid jsonParams/fields ({\"msg\": \"<reason>\"})."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the generation budget resets (mirrors Retry-After). Absent on the upload-limiter variant.","type":"number"}},"type":"object"}]}}},"description":"Too many uploads in the last minute. No Retry-After or rate-limit headers are sent; back off and retry. Unbilled (trial and public) keys also answer 429 when their per-minute generation budget is spent; that variant sets Retry-After and a numeric retry_after body field, so honor it before retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The model call failed transiently; nothing was billed. Safe to retry."}},"security":[{"bearerAuth":[]},{}],"summary":"Extract structured fields from an uploaded document","tags":["analysis"]}},"/api/v1/file-summarize":{"post":{"description":"Upload a document (.pdf, .docx, .pptx, .odt, .txt, .md, .html or .htm, up to 30MB) and summarize its text exactly like /api/v1/summarize. Options ride the optional jsonParams part. Text past the first 20,000 characters is not read; the response `document` object reports `truncated`. Billed like /api/v1/summarize on the characters used. Unbilled (trial and public) keys also answer 429 with Retry-After when their per-minute generation budget is spent.","externalDocs":{"url":"https://sapling.ai/docs/api/summarize/"},"operationId":"sapling_summarize_file","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional JSON object (send it as a file part or form field): {\"length\": \"short\" | \"medium\" | \"long\", \"key\": \"<API key>\", \"return_usage\": true}. `length` defaults to \"medium\", as on /api/v1/summarize.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"document":{"properties":{"characters":{"description":"Characters of text extracted from the file.","type":"integer"},"characters_used":{"description":"Characters summarized (and billed).","type":"integer"},"file_type":{"type":"string"},"truncated":{"type":"boolean"}},"type":"object"},"key_points":{"items":{"type":"string"},"type":"array"},"length":{"enum":["short","medium","long"],"type":"string"},"result":{"description":"Same as `summary` (legacy key).","type":"string"},"summary":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Same shape as a single /api/v1/summarize response, plus `document`."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"msg":{"type":"string"}},"type":"object"}}},"description":"Missing/unsupported file, unreadable document, no text ({\"error\": \"<reason>\"}), or invalid jsonParams/length ({\"msg\": \"<reason>\"})."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the generation budget resets (mirrors Retry-After). Absent on the upload-limiter variant.","type":"number"}},"type":"object"}]}}},"description":"Too many uploads in the last minute. No Retry-After or rate-limit headers are sent; back off and retry. Unbilled (trial and public) keys also answer 429 when their per-minute generation budget is spent; that variant sets Retry-After and a numeric retry_after body field, so honor it before retrying. The monthly API quota answers 429 too, with Retry-After set to the start of next month.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The model call failed transiently; nothing was billed. Safe to retry."}},"security":[{"bearerAuth":[]},{}],"summary":"Summarize an uploaded document","tags":["generation"]}},"/api/v1/inclusive":{"post":{"description":"Find non-inclusive or biased wording in a text \u2014 gendered defaults, ableist idioms, ageist framing, outdated terms for groups, classist or appearance-based language. Returns issues, each with the verbatim passage, its start/end offsets in the submitted text (null when the passage cannot be located), a category, a severity (low / medium / high), a brief note and a neutral replacement suggestion, plus a top-level inclusive boolean. Wording is flagged, not topics: text that discusses or quotes a term to critique it is not an issue. Use categories to restrict the check to a subset. The text is checked as submitted (markup included), so offsets always index it directly.","externalDocs":{"url":"https://sapling.ai/docs/api/inclusive/"},"operationId":"sapling_inclusive","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"categories":{"description":"Categories to check. Default: all of them.","items":{"enum":["gender","race_ethnicity","disability","age","lgbtq","religion","socioeconomic","appearance"],"type":"string"},"minItems":1,"type":"array"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to check. Checked as submitted \u2014 markup is not stripped.","maxLength":10000,"minLength":1,"pattern":"\\S","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":10000,"minLength":1,"pattern":"\\S","type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/inclusive/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Inclusive-language check","tags":["analysis"]}},"/api/v1/ingest/chunk_html":{"post":{"description":"Like chunk_text, for HTML input. Not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/chunk/"},"operationId":"sapling_chunk_html","requestBody":{"content":{"application/json":{"schema":{"properties":{"html":{"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"max_length":{"description":"Maximum chunk length in characters. Required in practice: omitting it answers 400.","minimum":1,"type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"step_size":{"default":0,"description":"Characters to advance between chunk starts; 0 means 10% of max_length.","minimum":0,"type":"integer"}},"required":["html","max_length"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"chunks":{"items":{"type":"string"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Chunks in document order."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Split HTML into chunks","tags":["files"]}},"/api/v1/ingest/chunk_text":{"post":{"description":"Split long text into overlapping chunks no longer than `max_length`, preferring sentence and whitespace boundaries. Not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/chunk/"},"operationId":"sapling_chunk_text","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"max_length":{"description":"Maximum chunk length in characters. Required in practice: omitting it answers 400.","minimum":1,"type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"step_size":{"default":0,"description":"Characters to advance between chunk starts; 0 means 10% of max_length.","minimum":0,"type":"integer"},"text":{"type":"string"}},"required":["text","max_length"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"chunks":{"items":{"type":"string"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Chunks in document order."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Split text into chunks","tags":["files"]}},"/api/v1/ingest/docx_to_text":{"post":{"description":"Upload a .docx and receive its text, tables included in document order. Not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/files/"},"operationId":"sapling_docx_to_text","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional part carrying a JSON object, e.g. {\"key\": \"<API key>\", \"return_usage\": true}, as an alternative to the query or header credential. Send it as a file part.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Extracted text."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"Missing `file` part, unsupported extension, or the document could not be read (empty, encrypted, corrupt, or no extractable text). Body: {\"error\": \"<reason>\"}. A request with no API key at all also answers 400 {\"error\": \"Unauthenticated\"}."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"$ref":"#/components/responses/UploadRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Extract text from a Word document","tags":["files"]}},"/api/v1/ingest/pdf_to_text":{"post":{"description":"Upload a PDF and receive its text, with layout line breaks and hyphenation repaired. Owner-locked PDFs are decrypted transparently; image-only PDFs answer 400. Not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/files/"},"operationId":"sapling_pdf_to_text","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional part carrying a JSON object, e.g. {\"key\": \"<API key>\", \"return_usage\": true}, as an alternative to the query or header credential. Send it as a file part.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Extracted text."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"Missing `file` part, unsupported extension, or the document could not be read (empty, encrypted, corrupt, or no extractable text). Body: {\"error\": \"<reason>\"}. A request with no API key at all also answers 400 {\"error\": \"Unauthenticated\"}."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"$ref":"#/components/responses/UploadRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Extract text from a PDF","tags":["files"]}},"/api/v1/jd-match":{"post":{"description":"Measure how closely a resume is tailored to the job description it was submitted against. Returns keyword_coverage (the share of the posting's salient keywords the resume uses), matched_keywords and missing_keywords (with counts), the passages the resume copies verbatim from the posting (copied_spans: runs of 6 or more shared words with start/end character offsets into the exact resume text, plus copied_fraction and has_copied_span), and a score from 0 to 1 with a level of low, moderate or high. The score is a transparent heuristic over those signals, not a probability, and says nothing about who or what wrote the resume: pair it with sapling_ai_detect for that. Useful for screening applications and for showing a candidate which keywords a resume misses. English-tuned. Not billed; both texts count against the rate limit.","externalDocs":{"url":"https://sapling.ai/docs/api/jd-match/"},"operationId":"sapling_jd_match","requestBody":{"content":{"application/json":{"schema":{"properties":{"job_description":{"description":"The job posting. It needs at least 5 distinct keywords; a shorter one is rejected.","maxLength":20000,"minLength":1,"pattern":"\\S","type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The resume, as plain text. Span offsets index this exact string.","maxLength":50000,"minLength":1,"pattern":"\\S","type":"string"}},"required":["text","job_description"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"copied_fraction":{"description":"Share of the resume's words inside a copied span.","maximum":1,"minimum":0,"type":"number"},"copied_spans":{"description":"At most 50, in order.","items":{"properties":{"end":{"type":"integer"},"start":{"type":"integer"},"text":{"type":"string"},"words":{"type":"integer"}},"type":"object"},"type":"array"},"copied_spans_total":{"type":"integer"},"has_copied_span":{"description":"Whether the resume shares any run of 6 or more words verbatim with the posting. Rare in resumes not tailored to the posting, though a stock phrase can trigger it, so check `copied_spans`.","type":"boolean"},"job_description_words":{"type":"integer"},"keyword_coverage":{"maximum":1,"minimum":0,"type":"number"},"level":{"enum":["low","moderate","high"],"type":"string"},"matched_keywords":{"items":{"properties":{"job_description_count":{"type":"integer"},"resume_count":{"type":"integer"},"term":{"type":"string"}},"type":"object"},"type":"array"},"missing_keywords":{"items":{"properties":{"job_description_count":{"type":"integer"},"term":{"type":"string"}},"type":"object"},"type":"array"},"resume_words":{"type":"integer"},"score":{"maximum":1,"minimum":0,"type":"number"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"version":{"type":"string"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/jd-match/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Resume vs job description match","tags":["analysis"]}},"/api/v1/langdetect":{"post":{"description":"Detect the language a text is written in. Returns an ISO 639-1 code, a confidence value, reliable (the recommended threshold: true when the confidence is high and the text has enough letters; short inputs like \"OK\" are never reliable) and script, the dominant writing system as an ISO 15924 code (e.g. Latn, Cyrl, Hani, Jpan).","externalDocs":{"url":"https://sapling.ai/docs/api/langdetect/"},"operationId":"sapling_detect_language","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"segments":{"description":"Also detect the language of each sentence-ish segment for mixed-language text (default false).","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"top_k":{"description":"Number of top language candidates to return (default 3).","maximum":10,"minimum":1,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/langdetect/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Language detection","tags":["detection"]}},"/api/v1/liveness":{"get":{"description":"Answers 200 while the API process is up.","externalDocs":{"url":"https://sapling.ai/docs/api"},"operationId":"sapling_liveness","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"msg":{"enum":["alive"],"type":"string"}},"type":"object"}}},"description":"Alive."}},"security":[],"summary":"Liveness probe","tags":["service"]}},"/api/v1/ner":{"post":{"description":"Find named entities in a text \u2014 people, organizations, locations, dates, times, money amounts, percentages, quantities, products, events \u2014 with character spans. Returns entities (each with its verbatim text, type, and start/end offsets into the exact submitted text) and types (the distinct types found). Every entity is a span the text actually contains \u2014 invented mentions are dropped. Offsets index the submitted text as-is (nothing is stripped or normalized), so they can be applied directly to your copy of the document. Use types to restrict recognition to a subset. Complements sapling_detect_pii: that tool finds checksum-validated identifiers (emails, cards, IBANs...), this one finds names and real-world references.","externalDocs":{"url":"https://sapling.ai/docs/api/ner/"},"operationId":"sapling_ner","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to analyze. Offsets index this exact string \u2014 HTML is not stripped, so pass the form you want spans into.","maxLength":10000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":10000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"types":{"description":"Entity types to recognize. Default: all of them.","items":{"enum":["person","organization","location","date","time","money","percent","quantity","product","event"],"type":"string"},"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/ner/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Named-entity recognition","tags":["detection"]}},"/api/v1/paraphrase":{"post":{"deprecated":true,"description":"DEPRECATED: use /api/v1/rephrase with mapping=\"paraphrase\". Rewrites text with a chosen transformation, exactly like /api/v1/rephrase but under its own rate-limit bucket. Input is limited to 4000 characters.","externalDocs":{"url":"https://sapling.ai/docs/api/rephrase/"},"operationId":"sapling_paraphrase","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"mapping":{"description":"Transformation to apply. Defaults to \"paraphrase\".","enum":["paraphrase","passive_to_active","active_to_passive","informal_to_formal","formal_to_informal","sentence_split","reword","generate_title","generate_acronym","generate_meta_description","summarize","expand","shorten","switch_tone","switch_tense"],"type":"string"},"num_results":{"description":"Number of alternatives to return (default 5).","type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"tense_mapping":{"description":"Target tense. Only used with mapping=\"switch_tense\".","enum":["simple past","past perfect","past continuous","past perfect continuous","simple present","present perfect","present continuous","present perfect continuous","simple future","future perfect","future continuous","future perfect continuous"],"type":"string"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"tone_mapping":{"description":"Target tone. Only used with mapping=\"switch_tone\".","enum":["straightforward","confident","friendly","empathetic","professional","casual","diplomatic","persuasive"],"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"hash":{"format":"uuid","type":"string"},"model_version":{"type":"string"},"original":{"type":"string"},"rephrase_type":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Alternatives: {\"results\": [{hash, original, replacement, rephrase_type, model_version}]}.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (missing/empty text, text over 4000 characters, invalid mapping). A TRANSIENT model failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the request would fit the bucket. Absent when it never can.","type":"number"}},"type":"object"}]}}},"description":"Rate limited. Wait retry_after seconds (also in the Retry-After header) and retry. If retry_after is absent, the request exceeds the bucket capacity and can never succeed unchanged. The monthly API quota answers 429 too, with Retry-After set to the start of next month. On this operation an anonymous (no API key) request over the free-usage character cap also answers 429, with no Retry-After header and no retry_after field \u2014 that request can never succeed unchanged; send an API key or shorten the text instead of retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Paraphrase text (deprecated)","tags":["generation"]}},"/api/v1/pdf-aidetect":{"post":{"description":"Upload a PDF; its extracted text (first 200,000 characters) is scored like /api/v1/aidetect with sentence scores. Billed like /api/v1/aidetect.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_aidetect_pdf","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"The document to upload.","format":"binary","type":"string"},"jsonParams":{"description":"Optional part carrying a JSON object, e.g. {\"key\": \"<API key>\", \"return_usage\": true}, as an alternative to the query or header credential. Send it as a file part.","format":"binary","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ai_fraction":{"description":"Share (0-1) of the text in sentences scoring >= 0.5; reports partially AI-written documents whose overall score stays below 0.5.","type":"number"},"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"score":{"type":"number"},"score_string":{"type":"string"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"sentence_scores":{"items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"sentence":{"type":"string"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Same shape as /api/v1/aidetect with sent_scores and score_string enabled."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"Missing `file` part, unsupported extension, or the document could not be read (empty, encrypted, corrupt, or no extractable text). Body: {\"error\": \"<reason>\"}. A request with no API key at all also answers 400 {\"error\": \"Unauthenticated\"}. A transient scoring failure also answers 400 {\"error\": \"Unexpected error\"}; that case is safe to retry after a short delay."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}},"description":"The uploaded file is over 30MB. Body: {\"error\": \"<reason>\"}."},"429":{"$ref":"#/components/responses/UploadRateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Detect AI-generated text in a PDF","tags":["detection"]}},"/api/v1/pii":{"post":{"description":"Detect personally identifiable information (emails, phone numbers, US SSNs, credit card numbers, IP addresses, IBANs, US bank routing numbers) in a text. Detection of those types is deterministic (regex + checksum validation, no ML), and every entity comes with exact character offsets (start/end) into the submitted text. Set redact=true to also receive redacted_text: the input with each entity replaced by a placeholder like [EMAIL]. Person names, organizations, and locations/street addresses are NOT detected by default: list person/organization/location in types explicitly to add LLM-backed detection of them (slower, and the text is then capped at 10000 characters).","externalDocs":{"url":"https://sapling.ai/docs/api/pii/"},"operationId":"sapling_detect_pii","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"redact":{"description":"If true, the response includes redacted_text with every detected entity replaced by its placeholder.","type":"boolean"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to scan. Offsets in the response refer to this exact string, so pass raw text (not HTML).","type":"string"},"types":{"description":"Restrict detection to these PII types. Defaults to all deterministic types; person, organization, and location run only when listed here explicitly.","items":{"enum":["email","phone","ssn","credit_card","ip_address","iban","us_bank_routing","person","organization","location"],"type":"string"},"type":"array"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/pii/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"PII detection and redaction","tags":["detection"]}},"/api/v1/profanity":{"post":{"description":"Split text on whitespace and label each token 1 (profane) or 0. Not billed.","externalDocs":{"url":"https://sapling.ai/docs/api/profanity/"},"operationId":"sapling_profanity","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"labels":{"items":{"enum":[0,1],"type":"integer"},"type":"array"},"toks":{"items":{"type":"string"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Tokens and aligned labels.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or empty text (\"Missing arguments.\").","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Flag profanity","tags":["detection"]}},"/api/v1/quality":{"post":{"description":"Score the writing quality of a text from 1 (poor) to 5 (excellent). Returns score: a fluency/grammaticality score from a language model. Set sentence_scores=true to also get a per-sentence breakdown (sentences with start/end offsets and their own score) to find the weakest sentences. Set rubric=true for an LLM-judged rubric: overall score, per-dimension scores (clarity, coherence, correctness, concision), a summary, and concrete issues each with the quoted excerpt, offsets, a note, and a suggested rewrite. rubric=true is billed at a higher rate than the plain score.","externalDocs":{"url":"https://sapling.ai/docs/api/quality/"},"operationId":"sapling_quality","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"rubric":{"description":"Also return the LLM rubric: overall + clarity/coherence/correctness/concision scores, summary and quoted issues with suggested rewrites (default false).","type":"boolean"},"sentence_scores":{"description":"Also return a 1-5 score per sentence (default false).","type":"boolean"},"text":{"description":"The plain text to score. HTML is not stripped \u2014 pass markup-free text so tags are not scored as words.","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/quality/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Writing quality score","tags":["analysis"]}},"/api/v1/rephrase":{"post":{"description":"Generate alternative phrasings of a text. mapping selects the transformation (default \"paraphrase\"); num_results controls how many alternatives are returned (default 5).","externalDocs":{"url":"https://sapling.ai/docs/api/rephrase/"},"operationId":"sapling_rephrase","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"mapping":{"description":"Transformation to apply. Defaults to \"paraphrase\".","enum":["paraphrase","passive_to_active","active_to_passive","informal_to_formal","formal_to_informal","sentence_split","reword","generate_title","generate_acronym","generate_meta_description","summarize","expand","shorten","switch_tone","switch_tense"],"type":"string"},"num_results":{"description":"Number of alternatives to return (default 5).","type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"tense_mapping":{"description":"Target tense. Only used with mapping=\"switch_tense\".","enum":["simple past","past perfect","past continuous","past perfect continuous","simple present","present perfect","present continuous","present perfect continuous","simple future","future perfect","future continuous","future perfect continuous"],"type":"string"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"tone_mapping":{"description":"Target tone. Only used with mapping=\"switch_tone\".","enum":["straightforward","confident","friendly","empathetic","professional","casual","diplomatic","persuasive"],"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/rephrase/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the request would fit the bucket. Absent when it never can.","type":"number"}},"type":"object"}]}}},"description":"Rate limited. Wait retry_after seconds (also in the Retry-After header) and retry. If retry_after is absent, the request exceeds the bucket capacity and can never succeed unchanged. On this operation an anonymous (no API key) request over the free-usage character cap also answers 429, with no Retry-After header and no retry_after field \u2014 that request can never succeed unchanged; send an API key or shorten the text instead of retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Rephrase / paraphrase","tags":["generation"]}},"/api/v1/reporting/api_endpoint_usage":{"post":{"description":"Characters per endpoint, bucketed by day, week or month. The body must be a non-empty JSON object.","externalDocs":{"url":"https://sapling.ai/docs/api/api-reporting/"},"operationId":"sapling_api_endpoint_usage","requestBody":{"content":{"application/json":{"schema":{"minProperties":1,"properties":{"end_days_back":{"default":0,"description":"Window end, in days before today.","minimum":0,"type":"integer"},"interval":{"default":"Daily","enum":["Daily","Weekly","Monthly"],"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"start_days_back":{"default":6,"description":"Window start, in days before today.","minimum":0,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"type":"object"},"last_updated":{"description":"ISO timestamp, or null."},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"{\"data\": {endpoint: {bucket: characters}}, \"last_updated\"}."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested window reaches further back than the maximum reporting range (about one year). MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"API usage by endpoint over time","tags":["account"]}},"/api/v1/reporting/api_quota_usage":{"post":{"description":"Quota, characters used, and suggestion accept/ignore counts over a window of days. Send a JSON body (it may be `{}`).","externalDocs":{"url":"https://sapling.ai/docs/api/api-reporting/"},"operationId":"sapling_api_quota_usage","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_days_back":{"default":0,"description":"Window end, in days before today.","minimum":0,"type":"integer"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"start_days_back":{"default":1,"description":"Window start, in days before today.","minimum":0,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"accepts":{"type":"integer"},"ignores":{"type":"integer"},"last_updated":{"description":"Unix epoch seconds. Falls back to 24h ago when no aggregation timestamp is cached.","type":"number"},"quota":{"type":"integer"},"usage":{"type":"integer"}},"type":"object"}}},"description":"Quota summary."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested window reaches further back than the maximum reporting range (about one year). MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Quota and usage summary","tags":["account"]}},"/api/v1/reporting/api_usage":{"post":{"description":"Characters and cost over a window of days, broken down by API key, endpoint, day and month. The body is optional.","externalDocs":{"url":"https://sapling.ai/docs/api/api-reporting/"},"operationId":"sapling_api_usage","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_days_back":{"default":0,"description":"Window end, in days before today.","minimum":0,"type":"integer"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"start_days_back":{"description":"Window start, in days before today. Defaults to the first of this month.","minimum":0,"type":"integer"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"by_api_key":{"type":"object"},"by_endpoint":{"type":"object"},"currency":{"type":"string"},"daily_usage":{"description":"Characters per day."},"end_date":{"type":"string"},"last_updated":{"description":"When usage was last aggregated."},"monthly_usage":{"description":"Characters per month."},"start_date":{"type":"string"},"total_characters":{"type":"integer"},"total_cost_usd":{"type":"number"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Usage report."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Non-integer or negative day offsets, or start before end."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested window reaches further back than the maximum reporting range (about one year). MCP OAuth access tokens are not accepted by this operation; send an API key."},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"API usage and cost report","tags":["account"]}},"/api/v1/reporting/api_user_activity":{"post":{"description":"Edits shown, accepted and ignored, plus active-user counts (logged-in and anonymous), over a window of days. Send a non-empty JSON body (unlike /api/v1/reporting/api_usage this handler rejects an absent or empty `{}` body with 400); the window defaults to the last 6 days when a field is omitted.","externalDocs":{"url":"https://sapling.ai/docs/api/api-reporting/"},"operationId":"sapling_api_user_activity","requestBody":{"content":{"application/json":{"schema":{"minProperties":1,"properties":{"end_days_back":{"default":0,"description":"Window end, in days before today.","minimum":0,"type":"integer"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"start_days_back":{"default":6,"description":"Window start, in days before today.","minimum":0,"type":"integer"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"active_users":{"properties":{"anonymous":{"type":"integer"},"logged_in":{"type":"integer"}},"type":"object"},"edits_accepted":{"type":"integer"},"edits_ignored":{"type":"integer"},"edits_shown":{"type":"integer"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Activity summary."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The requested window reaches further back than the maximum reporting range (about one year). MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"bearerAuth":[]},{}],"summary":"Suggestion activity and active-user report","tags":["account"]}},"/api/v1/safety":{"post":{"description":"Score a text for unsafe content across seven categories \u2014 toxicity, profanity, harassment, hate_speech, self_harm, sexual, violence \u2014 each as a 0-1 probability. Returns scores (all seven), flagged (whether any category reached the threshold, default 0.5) and flagged_categories. With spans=true, also returns spans: the specific offending passages, each with its text, start/end offsets into the submitted text, per-category scores and flagged_categories \u2014 use it to highlight, quote, or redact just the violating passage instead of rejecting the whole text.","externalDocs":{"url":"https://sapling.ai/docs/api/safety/"},"operationId":"sapling_safety","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"spans":{"description":"true = also return the offending passages as spans with offsets and per-passage scores. Default false.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","maxLength":20000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":20000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"threshold":{"description":"Flagging cut-off on each category score (default 0.5).","maximum":1,"minimum":0,"type":"number"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/safety/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Content safety check","tags":["detection"]}},"/api/v1/sentence_split":{"post":{"description":"Rewrite text, breaking run-on sentences into shorter ones. Input is limited to 400 characters.","externalDocs":{"url":"https://sapling.ai/docs/api/rephrase/"},"operationId":"sapling_sentence_split","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional session identifier used to group feedback events.","type":"string"},"text":{"maxLength":400,"type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"properties":{"hash":{"format":"uuid","type":"string"},"model_version":{"type":"string"},"original":{"type":"string"},"rephrase_type":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Alternatives: {\"results\": [{hash, original, replacement, rephrase_type, model_version}]}. Empty when no split improves the text.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (missing/empty text, or text over 400 characters). A TRANSIENT model failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the request would fit the bucket. Absent when it never can.","type":"number"}},"type":"object"}]}}},"description":"Rate limited. Wait retry_after seconds (also in the Retry-After header) and retry. If retry_after is absent, the request exceeds the bucket capacity and can never succeed unchanged. The monthly API quota answers 429 too, with Retry-After set to the start of next month. On this operation an anonymous (no API key) request over the free-usage character cap also answers 429, with no Retry-After header and no retry_after field \u2014 that request can never succeed unchanged; send an API key or shorten the text instead of retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Split run-on sentences","tags":["generation"]}},"/api/v1/sentiment":{"post":{"description":"Classify the sentiment of a text (positive / neutral / negative). Returns overall and per-sentence sentiment with confidence scores.","externalDocs":{"url":"https://sapling.ai/docs/api/sentiment/"},"operationId":"sapling_sentiment","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"},{"type":"array"}]}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/sentiment/ A bare JSON array (no per-sentence results) is the degraded shape served when sentence tokenization fails upstream.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"204":{"description":"The text contained no scoreable sentences (empty or markup-only input). Empty body.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Sentiment analysis","tags":["analysis"]}},"/api/v1/seo":{"post":{"description":"Analyze a page or article for on-page SEO and generate metadata. Returns stats (words, sentences, paragraphs, reading time, Flesch reading ease and grade), per-target-keyword count/density/whether it appears in the first 100 words, top_terms (the most frequent content words and phrases), and suggestions: title-tag candidates (the model aims for <=60 chars; any over a 90-char hard cap are dropped), meta-description candidates (aims for 120-155 chars; hard cap 220), a URL slug (null if none could be derived) and focus-keyword ideas, written in the language of the text. Pass keywords to have them worked into the suggestions. Set suggestions=false for the free stats-only analysis (suggestions are the billed part). lang (ISO 639-1, default \"en\") selects the readability formulas; unsupported languages get null readability.","externalDocs":{"url":"https://sapling.ai/docs/api/seo/"},"operationId":"sapling_seo","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"keywords":{"description":"Target keyword phrases, most important first (max 10). Each is measured in the text and steered into the suggestions.","items":{"type":"string"},"maxItems":10,"type":"array"},"lang":{"description":"ISO 639-1 language code of the text (default \"en\"). Selects the readability formulas; supported for en, de, es, fr, it, nl, pl, ru \u2014 other codes are accepted and get null readability.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"suggestions":{"description":"Generate titles/meta descriptions/slug/keywords with the LLM (default true). false = deterministic stats only.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/seo/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"SEO analysis and metadata","tags":["analysis"]}},"/api/v1/simplify":{"post":{"description":"Rewrite a text in plain language at a target reading level, keeping all of its content, structure and language (nothing is summarized or dropped). Returns simplified (the rewrite) plus a before/after readability block (Flesch-Kincaid grade and reading ease) when the language supports it, so the improvement is verifiable. Use preserve_terms for names or defined terms that must survive verbatim. Pairs with sapling_readability_statistics for scoring text first.","externalDocs":{"url":"https://sapling.ai/docs/api/simplify/"},"operationId":"sapling_simplify","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"ISO 639-1 code used to pick the readability formula for the before/after scores and the billed language. Omit for auto-detection (falls back to \"en\"). The rewrite itself always stays in the text's own language.","maxLength":20,"minLength":2,"pattern":"\\S","type":"string"},"preserve_terms":{"description":"Terms the rewrite must keep exactly as written (product names, defined legal terms).","items":{"maxLength":100,"minLength":1,"pattern":"\\S","type":"string"},"maxItems":20,"type":"array"},"reading_level":{"description":"Target audience: \"plain\" (plain-language style for a general audience, the default), \"elementary\" (~US grade 3-5), \"middle_school\" (~grade 6-8) or \"high_school\" (~grade 9-10).","enum":["plain","elementary","middle_school","high_school"],"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to simplify. Sent to the model as-is \u2014 markup and line structure are preserved, not stripped.","maxLength":5000,"minLength":1,"pattern":"\\S","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":5000,"minLength":1,"pattern":"\\S","type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/simplify/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Plain-language simplification","tags":["generation"]}},"/api/v1/source-match":{"post":{"description":"Find the passages a text copies word for word from source documents you supply: reference answers, earlier submissions, the pages a draft was researched from, an internal corpus. Returns similarity (the share of the text's words inside a copied span from any source) and, for each source that shares a span, its index and id, matched_words, matched_fraction and spans (start/end character offsets into the exact submitted text, the word count and the copied text). Matching ignores case, punctuation and curly vs straight apostrophes. Set exclude_quotes to ignore quoted passages, as plagiarism checkers do. It detects copying, not paraphrase or AI writing (pair it with sapling_ai_detect), and it does not search the web: pass the sources you want checked. Not billed; the text and every source count against the rate limit. A source can also be a url (up to 5 per request): the page or linked PDF/DOCX is fetched and its readable text compared; a URL that cannot be read is skipped and reported in url_sources.","externalDocs":{"url":"https://sapling.ai/docs/api/source-match/"},"operationId":"sapling_source_match","requestBody":{"content":{"application/json":{"schema":{"properties":{"exclude_quotes":{"description":"true = words inside double quotation marks (any common style) or on block-quote lines starting with > never count as matched. Default false.","type":"boolean"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"min_words":{"description":"Shortest shared run of words reported. Default 8.","maximum":50,"minimum":6,"type":"integer"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"sources":{"description":"Documents to compare against, as objects with a text or a url, and an optional id. Combined source text is limited to 300,000 characters; at most 5 sources can be URLs, and each fetched page is cut at 100,000 characters.","items":{"additionalProperties":false,"oneOf":[{"required":["text"]},{"required":["url"]}],"properties":{"id":{"description":"Your label for the source (a URL or file name), echoed back. Unique per request.","maxLength":128,"minLength":1,"type":"string"},"text":{"maxLength":100000,"type":"string"},"url":{"description":"An http(s) page or document to fetch instead of sending text.","maxLength":2048,"type":"string"}},"type":"object"},"maxItems":20,"minItems":1,"type":"array"},"text":{"description":"The text to check. Span offsets index this exact string.","maxLength":50000,"minLength":1,"pattern":"\\S","type":"string"}},"required":["text","sources"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"exclude_quotes":{"type":"boolean"},"matched_words":{"type":"integer"},"min_words":{"type":"integer"},"quoted_words":{"description":"Words set aside by `exclude_quotes` (0 when it is off). They still count in `text_words`.","type":"integer"},"similarity":{"description":"Share of the text's words inside a span from any source (overlaps count once).","maximum":1,"minimum":0,"type":"number"},"sources":{"description":"Sources sharing at least one span, most matched words first. Sources without a span are omitted.","items":{"properties":{"id":{"description":"The request's `id` (a string), or null when none was sent."},"index":{"description":"Position in the request's `sources`.","type":"integer"},"matched_fraction":{"maximum":1,"minimum":0,"type":"number"},"matched_words":{"type":"integer"},"spans":{"items":{"properties":{"end":{"type":"integer"},"start":{"type":"integer"},"text":{"type":"string"},"words":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"},"sources_checked":{"type":"integer"},"text_words":{"type":"integer"},"url_sources":{"description":"Present when any source was a `url`: one entry per URL source, in request order. A source whose `status` is `error` was skipped and is not in `sources_checked`.","items":{"properties":{"characters":{"description":"Characters of page text matched.","type":"integer"},"content_type":{"type":"string"},"id":{"description":"The request's `id` (a string), or null when none was sent."},"index":{"description":"Position in the request's `sources`.","type":"integer"},"msg":{"type":"string"},"reason":{"description":"Stable failure label, e.g. timeout, unreachable, invalid_url, http_status, unsupported_content_type, no_text, deadline.","type":"string"},"status":{"enum":["ok","error"],"type":"string"},"title":{"type":"string"},"truncated":{"description":"Only the first 100,000 characters of the page text were matched.","type":"boolean"},"url":{"description":"Final URL after redirects (the requested URL when the fetch failed).","type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"version":{"type":"string"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/source-match/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Every source was a URL and none had readable text (a non-2xx HTTP status, an unsupported content type or an unreadable document). `url_sources` gives each URL's reason.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Every source was a URL and none could be read, at least one because the fetch failed (timeout or connection failure); safe to retry later. `url_sources` gives each URL's reason.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Verbatim source match","tags":["analysis"]}},"/api/v1/spellcheck":{"post":{"description":"Check text for spelling errors only (no grammar or style suggestions). Returns edits in the same format as sapling_grammar_check. Faster and cheaper than a full grammar check when only misspellings matter. A result carrying a degraded object is partial; call again for a complete result.","externalDocs":{"url":"https://sapling.ai/docs/api/spellcheck/"},"operationId":"sapling_spellcheck","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"ISO 639-1 language code of the text. Defaults to \"en\".","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"session_id":{"description":"Optional stable identifier for the document being checked.","type":"string"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"degraded":{"description":"Present only on a partial result: a model stage could not process some sentences in time, so those sentences may be missing some or all of their corrections (a failed primary stage leaves a sentence unchecked; a failed secondary stage, e.g. neural spellcheck or postprocessing, drops only that stage's corrections). Every edit returned is still valid. Absent from a fully successful response. Retry the request (after a short backoff) for a complete result.","properties":{"reason":{"enum":["model_timeout","model_unavailable","model_error"],"type":"string"},"sentences_degraded":{"minimum":1,"type":"integer"},"sentences_total":{"minimum":1,"type":"integer"}},"required":["sentences_degraded","sentences_total","reason"],"type":"object"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"},{"type":"array"}]}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/spellcheck/ With noformat=true (the SDK response shape) the body is a bare array of edit objects instead. A partial result (some corrections may be missing) adds a `degraded` object; retry for a complete result.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The team_id option names a team that does not exist or that the API key's user is not a member of.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Spelling-only check","tags":["proofreading"]}},"/api/v1/statistics":{"post":{"description":"Compute readability statistics for a text: grade-level readability scores, estimated reading time, and counts of characters, words, and sentences.","externalDocs":{"url":"https://sapling.ai/docs/api/statistics/"},"operationId":"sapling_readability_statistics","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"ISO 639-1 language code of the text. Defaults to \"en\".","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/statistics/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Readability statistics","tags":["analysis"]}},"/api/v1/styleguide":{"post":{"description":"Check a text for compliance with caller-supplied style rules (house style, brand voice, editorial guidelines). Returns violations \u2014 each with the verbatim offending passage, its start/end offsets in the submitted text (null when the passage cannot be located), the violated rule name, a brief note and a compliant rewrite suggestion \u2014 plus a top-level compliant boolean. Only the listed rules are enforced; an empty violations list means the text complies. The text is checked as submitted (markup included), so offsets always index it directly. Provide exactly one of rules (inline) or ruleset (the name of a rule set saved via the API).","externalDocs":{"url":"https://sapling.ai/docs/api/styleguide/"},"operationId":"sapling_styleguide","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text","rules"]},{"required":["text","ruleset"]},{"required":["texts","rules"]},{"required":["texts","ruleset"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"rules":{"description":"The style rules to enforce: 1-20 rules, each a rule name string (at most 80 characters) or a {name, description} object (description at most 400 characters adds nuance the model follows). Names must be unique case-insensitively.","items":{"anyOf":[{"maxLength":80,"minLength":1,"type":"string"},{"additionalProperties":false,"properties":{"description":{"maxLength":400,"type":"string"},"name":{"maxLength":80,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}]},"maxItems":20,"minItems":1,"type":"array"},"ruleset":{"description":"The name of a saved ruleset (created via POST /api/v1/styleguide/rulesets) to check against in place of inline rules. Matched case-insensitively within the API key's account (its team, for team keys). Provide exactly one of rules or ruleset.","maxLength":100,"minLength":1,"type":"string"},"text":{"description":"The text to check. Checked as submitted \u2014 markup is not stripped.","maxLength":10000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":10000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/styleguide/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A named resource in the request does not exist for the authenticated account \u2014 e.g. a `ruleset` naming a saved rule set that was never created, was deleted, or belongs to another account. Correct or create the name; retrying unchanged will not help.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Check text against a style guide","tags":["analysis"]}},"/api/v1/styleguide/rulesets":{"delete":{"description":"Delete a saved rule set by name. The name may be sent as a query parameter or as `name` in a JSON body.","externalDocs":{"url":"https://sapling.ai/docs/api/styleguide/"},"operationId":"sapling_delete_style_ruleset","parameters":[{"description":"Rule set name (alternatively in the body).","in":"query","name":"name","required":false,"schema":{"type":"string"}},{"description":"Sapling API key, as an alternative to the \"Authorization: Bearer <key>\" header.","in":"query","name":"key","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"name":{"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"deleted":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Deleted.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or invalid name.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot manage rule sets; use a private key. MCP OAuth access tokens are not accepted by this operation; send an API key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A named resource in the request does not exist for the authenticated account \u2014 e.g. a `ruleset` naming a saved rule set that was never created, was deleted, or belongs to another account. Correct or create the name; retrying unchanged will not help.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Delete a style-guide rule set","tags":["analysis"]},"get":{"description":"Rule sets saved for this account (or the key's team), usable by name via the `ruleset` option of /api/v1/styleguide.","externalDocs":{"url":"https://sapling.ai/docs/api/styleguide/"},"operationId":"sapling_list_style_rulesets","parameters":[{"in":"query","name":"return_usage","required":false,"schema":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"rulesets":{"items":{"properties":{"created_at":{"description":"Naive ISO 8601 timestamp (UTC, no offset).","type":"string"},"name":{"type":"string"},"rules":{"items":{"properties":{"description":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"},"updated_at":{"description":"Naive ISO 8601 timestamp (UTC, no offset).","type":"string"}},"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Saved rule sets, ordered by name.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot manage rule sets; use a private key. MCP OAuth access tokens are not accepted by this operation; send an API key."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"summary":"List saved style-guide rule sets","tags":["analysis"]},"post":{"description":"Upsert a named rule set (names match case-insensitively). An account can hold up to 100 rule sets.","externalDocs":{"url":"https://sapling.ai/docs/api/styleguide/"},"operationId":"sapling_save_style_ruleset","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"name":{"maxLength":100,"minLength":1,"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"rules":{"description":"Rule names must be unique (case-insensitive).","items":{"oneOf":[{"maxLength":80,"type":"string"},{"properties":{"description":{"maxLength":400,"type":"string"},"name":{"maxLength":80,"type":"string"}},"required":["name"],"type":"object"}]},"maxItems":20,"minItems":1,"type":"array"}},"required":["name","rules"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"created":{"type":"boolean"},"ruleset":{"properties":{"created_at":{"description":"Naive ISO 8601 timestamp (UTC, no offset).","type":"string"},"name":{"type":"string"},"rules":{"items":{"properties":{"description":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"},"updated_at":{"description":"Naive ISO 8601 timestamp (UTC, no offset).","type":"string"}},"type":"object"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"The saved rule set, and whether it was newly created.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid name or rules, or the 100 rule set limit is reached.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The public (client-side) API key cannot manage rule sets; use a private key. MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Create or replace a style-guide rule set","tags":["analysis"]}},"/api/v1/summarize":{"post":{"description":"Summarize a longer text, webpage or email thread (HTML input is accepted and flattened). Returns a prose `summary` plus a `key_points` list, sized by the optional `length` option.","externalDocs":{"url":"https://sapling.ai/docs/api/summarize/"},"operationId":"sapling_summarize","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"length":{"description":"Target summary size: \"short\" (1-2 sentences), \"medium\" (one paragraph, the default) or \"long\" (a few short paragraphs).","enum":["short","medium","long"],"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/summarize/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"retry_after":{"description":"Seconds until the request would fit the bucket. Absent when it never can.","type":"number"}},"type":"object"}]}}},"description":"Rate limited. Wait retry_after seconds (also in the Retry-After header) and retry. If retry_after is absent, the request exceeds the bucket capacity and can never succeed unchanged. On this operation an anonymous (no API key) request over the free-usage character cap also answers 429, with no Retry-After header and no retry_after field \u2014 that request can never succeed unchanged; send an API key or shorten the text instead of retrying.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Summarize text","tags":["generation"]}},"/api/v1/thesaurus":{"post":{"description":"Nearest-neighbor terms and synonyms for a word or short phrase (the query is truncated to 100 characters).","externalDocs":{"url":"https://sapling.ai/docs/api/similar-terms/"},"operationId":"sapling_similar_terms","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"query":{"type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"neighbors":{"description":"[similarity, term] pairs.","items":{"items":{},"type":"array"},"type":"array"},"synonyms":{"items":{"type":"string"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Neighbors as [similarity, term] pairs, plus synonyms.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"MCP OAuth access tokens are not accepted by this operation; send an API key."},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The embeddings service failed transiently; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"security":[{"bearerAuth":[]},{}],"summary":"Find similar terms","tags":["analysis"]}},"/api/v1/tone":{"post":{"description":"Classify the emotional tone of a text (e.g. friendly, confident, sad, angry). Returns overall and per-sentence tone labels with confidence scores.","externalDocs":{"url":"https://sapling.ai/docs/api/tone/"},"operationId":"sapling_tone","requestBody":{"content":{"application/json":{"schema":{"properties":{"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"text":{"description":"The text to process. Plain text or HTML (tags are handled server-side).","type":"string"}},"required":["text"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"properties":{"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"},{"type":"array"}]}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/tone/ A bare JSON array (no per-sentence results) is the degraded shape served when sentence tokenization fails upstream.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Tone classification","tags":["analysis"]}},"/api/v1/translate":{"post":{"description":"Translate a text into a target language with an LLM. Returns translation, the detected source language (source_lang code + source_lang_name; the detection is reported, never guessed from the hint) and the normalized target (target_lang, target_lang_name). Line breaks, markup and placeholders are preserved in place. target_lang and source_lang accept an ISO 639 code (\"fr\", \"zh-TW\") or an English language name (\"French\"); region variants zh-CN/zh-TW/zh-HK, pt-BR/pt-PT, en-GB/en-US, fr-CA and es-419 are supported as targets. Optional formality picks a formal or informal register where the target language distinguishes them.","externalDocs":{"url":"https://sapling.ai/docs/api/translate/"},"operationId":"sapling_translate","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"required":["text"]},{"required":["texts"]}],"properties":{"formality":{"description":"Optional register: \"formal\" (vous/Sie/usted) or \"informal\" (tu/du/t\u00fa). Omit for the model default.","enum":["formal","informal"],"type":"string"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"source_lang":{"description":"Optional hint for the source language (same forms as target_lang). The text itself wins if they disagree.","maxLength":40,"type":"string"},"target_lang":{"description":"Language to translate into: ISO 639 code (\"fr\", \"zh-TW\") or English name (\"French\").","maxLength":40,"type":"string"},"text":{"description":"The text to translate. Sent to the model as-is \u2014 markup and line structure are preserved, not stripped.","maxLength":5000,"minLength":1,"type":"string"},"texts":{"description":"Batch form: 1 to 10 texts, each processed with the same options as a single request. Send exactly one of `text` or `texts`; the response is then {\"results\": [...]}, one single-text response per input text in input order. Size limits are on the endpoint's docs page -- most cap the combined length of all items at the single-text limit.","items":{"maxLength":5000,"minLength":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"}},"required":["target_lang"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"description":"Present only for a batch (`texts`) request: one entry per input text, in input order, each shaped exactly like the single-text response.","items":{"type":"object"},"type":"array"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/translate/ A batch (`texts`) request answers {\"results\": [...]} instead: one single-text response per input text, in input order.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check such as a size limit or empty text). Validator rejections prefix `msg` with \"400 Bad Request:\".","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The upstream model call failed or returned an unusable result. The response is neither cached nor billed; safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"Translate text","tags":["generation"]}},"/api/v1/url-aidetect":{"post":{"description":"Fetch a public web page (or a linked .pdf, .docx, .pptx, .odt, .txt or .md document) and score how likely its main text is to be AI-generated. Use this instead of sapling_ai_detect when you have a link rather than the text: Sapling fetches the page itself, drops navigation, headers, footers, forms and hidden elements, and scores only the main readable text (the largest <article>, else <main>). Returns the same fields as sapling_ai_detect (score from 0 = likely human to 1 = likely AI, ai_fraction, verdict, segments, low_confidence, per-sentence scores by default, and the scored text) plus source: the final URL after redirects, the page title, its content type, the number of characters scored (and billed) and whether the page was truncated. Only http(s) URLs that resolve to public addresses are fetched. A page that is down, blocks automated requests, or has no readable text is reported as an error, not a score. For long pages set sent_scores=false to keep the result small.","externalDocs":{"url":"https://sapling.ai/docs/api/detector/"},"operationId":"sapling_ai_detect_url","requestBody":{"content":{"application/json":{"schema":{"properties":{"create_report":{"default":false,"description":"Also save the result as a shareable report and return its link in report (a single text only, not texts). The report is saved to your AI detector history, where you can revoke the link; anyone with the link can view the text and its scores until it is revoked or expires 90 days after creation. Requires your private API key: OAuth access tokens and public API keys get 400, as does combining it with zero_retention. No report is made (report is null, see report_skip_reason) when your team keeps no data, AI detector history or text retention is turned off, or the account email is unconfirmed; the request is still scored and billed.","type":"boolean"},"key":{"description":"Sapling API key. Required when no \"Authorization: Bearer <key>\" header is sent; when both are sent, the body key takes precedence over the header.","type":"string"},"lang":{"description":"Language of the page: en, ar, de, es, fr, it, ja, ko, nl, pl, pt, ro, ru, sv, tr or zh. Omit (or \"auto\") to detect it; other languages are rejected.","type":"string"},"return_usage":{"default":false,"description":"When true, a successful JSON-object response additionally carries \"usage\": {\"characters\": <n>} \u2014 the billable character count this request submitted (0 for unbilled requests; the 2.5x adjustment for logographic languages is included, so CJK requests report more than their raw length). Repeat texts inside the billing deduplication window are still counted here even though they are not re-charged, so the number is an upper bound on the final charge. Responses whose body is not a JSON object (e.g. bare-array response formats) cannot carry the field. An existing usage field (such as account/status or completion token usage) is preserved unchanged.","type":"boolean"},"score_string":{"description":"Also return score_string, an HTML rendering of the scored text highlighted by score (default false).","type":"boolean"},"sent_scores":{"description":"Include per-sentence scores (default true).","type":"boolean"},"url":{"description":"The http(s) URL of the page or document to check. A bare host/path gets https://.","maxLength":2048,"type":"string"},"version":{"description":"Pin a detector model version. Omit for the default.","type":"string"},"zero_retention":{"description":"Keep no copy of the text: the result is not cached (so no certificate hash), and usage is logged without the text. Default false; always on for teams with data retention disabled.","type":"boolean"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ai_fraction":{"type":"number"},"insufficient_text_reasons":{"description":"Present only when the request set min_words: why the text is out of scope (empty when it is in scope). below_min_words: fewer words than min_words. list_format: mostly bullet or numbered lines.","items":{"enum":["below_min_words","list_format"],"type":"string"},"type":"array"},"low_confidence":{"description":"True when the input is of a kind with a higher false-positive rate; see low_confidence_reasons.","type":"boolean"},"low_confidence_reasons":{"description":"short_text: under 500 characters. list_format: mostly bullet or numbered lines.","items":{"enum":["short_text","list_format"],"type":"string"},"type":"array"},"report":{"description":"The shareable report for this result (create_report: true), or null when none was made.","properties":{"expires_at":{"description":"When the link stops resolving unless revoked or deleted sooner.","format":"date-time","type":"string"},"id":{"description":"AI detector history entry id.","type":"string"},"shared_at":{"format":"date-time","type":"string"},"url":{"description":"Public report link.","type":"string"}}},"report_skip_reason":{"description":"Why report is null: nonpersist (team keeps no data), disabled (AI detector history off), text_not_retained (history keeps no text), unconfirmed_email, quota (history full), unscorable, error.","enum":["nonpersist","disabled","text_not_retained","unconfirmed_email","quota","unscorable","error"],"type":"string"},"score":{"type":"number"},"segments":{"description":"Contiguous passages of sentences scoring >= 0.5, as character offsets into text, with their length-weighted score. Absent when sentence offsets are unavailable.","items":{"properties":{"end":{"type":"integer"},"score":{"type":"number"},"start":{"type":"integer"}},"type":"object"},"type":"array"},"sentence_scores":{"items":{"type":"object"},"type":"array"},"source":{"properties":{"characters":{"description":"Characters scored (and billed).","type":"integer"},"content_type":{"type":"string"},"title":{"type":"string"},"truncated":{"description":"Part of the page or document was not scored (over 2MB of HTML, 15MB of document, or 200,000 characters).","type":"boolean"},"url":{"description":"Final URL after redirects.","type":"string"}},"type":"object"},"text":{"type":"string"},"usage":{"description":"Present only when the request sent return_usage: true. characters is the billable character count the request submitted; see the return_usage request field for the exact semantics.","properties":{"characters":{"type":"integer"}},"type":"object"},"verdict":{"description":"Plain-language summary: mixed when part of the text scores as AI (ai_fraction >= 0.2) or the overall score is >= 0.5 with less than 80% of the text scoring as AI. insufficient_text only when the request set min_words and the text is out of scope (see insufficient_text_reasons). Absent if the text could not be scored.","enum":["human","mixed","ai","insufficient_text"],"type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/detector/","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request (malformed JSON, a missing or invalid argument, or an endpoint-level check). NOTE: on this endpoint a TRANSIENT upstream model/service failure is also reported as a 400 whose msg starts with \"Unexpected error\" \u2014 that case is not a caller error and is safe to retry after a short delay.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The page was fetched but cannot be scored: a non-2xx HTTP status, an unsupported content type, an oversized or unreadable document, or no readable text.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error. Report persistent occurrences to support@sapling.ai.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The URL could not be fetched (timeout or connection failure); safe to retry later.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unable to serve the request (e.g. model servers saturated). Honor Retry-After and retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}}}},"summary":"AI-generated text detection for a web page","tags":["detection"]}},"/api/v1/version":{"get":{"description":"Release and build identifiers of the serving deployment.","externalDocs":{"url":"https://sapling.ai/docs/api"},"operationId":"sapling_version","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"build":{"type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Version."}},"security":[],"summary":"Server version","tags":["service"]}}},"security":[{"bearerAuth":[]},{"oauth2":["sapling:api"]},{}],"servers":[{"description":"The deployment serving this document","url":"https://api.sapling.ai"}],"tags":[{"description":"Grammar and spelling correction.","name":"proofreading"},{"description":"Text rewriting, summarization, translation, and completion.","name":"generation"},{"description":"AI-content, language, PII, named-entity, and unsafe-content detection.","name":"detection"},{"description":"Tone, sentiment, readability, quality, SEO, classification, extraction, style-guide compliance, and inclusive language.","name":"analysis"},{"description":"PDF/Word text extraction and text chunking.","name":"files"},{"description":"API key status, usage and quota reporting.","name":"account"},{"description":"Health and version probes (no API key).","name":"service"},{"description":"Other Sapling language endpoints.","name":"language-api"}]}
