analysis

SEO analysis and metadata

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.

post/api/v1/seo

Request

  • Base URL: https://api.sapling.ai
  • URL: https://api.sapling.ai/api/v1/seo
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.sapling.ai/oauth/authorize, token URL https://api.sapling.ai/oauth/token, scopes: sapling:api)
    • none

Request body

keystring

Sapling API key. Required when no "Authorization: Bearer <key>" header is sent; when both are sent, the body key takes precedence over the header.

keywordsstring[]

Target keyword phrases, most important first (max 10). Each is measured in the text and steered into the suggestions.

langstring

ISO 639-1 language code of the text (default "en"). Selects the readability formulas; supported for en, de, es, fr, it, nl, pl, ru — other codes are accepted and get null readability.

return_usageboolean

When true, a successful JSON-object response additionally carries "usage": {"characters": <n>} — 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.

suggestionsboolean

Generate titles/meta descriptions/slug/keywords with the LLM (default true). false = deterministic stats only.

textstring required

The text to process. Plain text or HTML (tags are handled server-side).

Response

Successful response. Field-level schemas and examples: https://sapling.ai/docs/api/seo/

Changes

No recorded changes to this operation across all 1 revision of this API.