Aautoranko

API reference

SEO toolkit

Standalone endpoints that help any website rank, plain HTML included, with no connected WordPress site required. Audit a page, research keywords, write articles, metadata and headings, generate structured data, robots.txt and sitemaps, rewrite copy and preview Google results. The AI-powered endpoints use the account's monthly AI-call allowance; the computed ones are free. Results are saved to your account unless you send save: false: browse them in Dashboard → SEO Lab or with GET /seo/analyses.

15 endpointsBase URL https://autoranko.com/api/public/v1Every request needs a bearer token

Audit a page

POSThttps://autoranko.com/api/public/v1/seo/analyze

Fetches any public page, from a CMS page to a hand-written HTML file, and audits it for search in four layers. page holds the facts parsed from the HTML: title, meta description, canonical, robots, headings, word count, images, links, Open Graph, JSON-LD and hreflang. heuristics is a rule-based audit scored out of 100. serp_preview shows how the current title and description render on Google. expert is a senior consultant's review, written by AI.

The rule-based layers are deterministic: the same page always gets the same score, issues and checks, so you can track them over time, and their notes are in English. The expert review adds what rules can't judge, such as search intent, persuasiveness and the biggest blocker, with prioritized recommendations in the page's language.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • urlstring (uri)Required
    The page to audit. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/analyze \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://gladiacteur.com"
  }'

Response

200OKThe page facts, the scored audit, the SERP preview and the expert review.

Response bodyapplication/json
  • pageobject
    What the parser found on the page.
    page keys(27)SeoPage
    • urlstring (uri)
      The URL as requested, normalized (https:// added to a bare host).
    • final_urlstring (uri)
      The URL the page was read from, after redirects (at most 3 are followed).
    • http_statusinteger
      HTTP status of the final response. Always below 400: an error page gets 422 fetch_failed instead.
    • httpsboolean
      true when final_url uses HTTPS.
    • titlestring or null
      Text of the <title> tag, or null if the page has none.
    • title_lengthinteger
      Characters in title (0 without one).
    • meta_descriptionstring or null
      Content of the meta description tag, or null if the page has none.
    • meta_description_lengthinteger
      Characters in meta_description (0 without one).
    • canonicalstring or null
      The rel=canonical URL as written in the HTML (it can be relative), or null.
    • robots_metastring or null
      Content of the robots meta tag, such as index, follow, or null.
    • langstring or null
      The <html lang> attribute, such as fr-FR, or null.
    • viewportboolean
      Whether the page has a viewport meta tag.
    • charsetboolean
      Whether the page declares its character set in a meta tag.
    • faviconboolean
      Whether the page declares a favicon.
    • h1array of strings
      Text of the <h1> headings, in page order (at most 25).
    • h2array of strings
      Text of the <h2> headings, in page order (at most 25).
    • h3array of strings
      Text of the <h3> headings, in page order (at most 25).
    • word_countinteger
      Words of visible text, leaving out scripts, styles, <nav> and <footer>.
    • images_totalinteger
      Number of <img> tags.
    • images_missing_altinteger
      <img> tags whose alt text is missing or empty (decorative images with alt="" included).
    • links_internalinteger
      Links to the page's own host (www. ignored).
    • links_externalinteger
      Links to other hosts.
    • open_graphobject
      Every og:* meta tag, keyed by property, such as og:title.
    • twitter_cardobject
      Every twitter:* meta tag, keyed by name, such as twitter:card.
    • json_ld_typesarray of strings
      The @type values in the page's JSON-LD, @graph nodes included, without duplicates. (unparseable JSON-LD) marks a block that isn't valid JSON.
    • hreflangarray of objects
      The page's hreflang alternate links.
      hreflang items(2)
      • langstring
        The hreflang value, such as fr or x-default.
      • hrefstring
        The alternate URL, as written.
    • html_size_bytesinteger
      Size of the HTML in characters, as read (the fetch stops at 5 MB).
  • heuristicsobject
    The rule-based audit.
    heuristics keys(2)
    • scoreinteger
      On-page score from 0 to 100: 100 minus 18 per critical, 10 per major and 4 per minor issue, never below 0.
    • issuesarray of objects
      Every problem found, most severe first. An empty list means the page passed every rule.
      issues items(4)SeoIssue
      • severitystring
        How much the issue costs: critical takes 18 points off score, major 10 and minor 4.

        One ofcriticalmajorminor

      • elementstring
        What the issue is about, such as title, h1, canonical, images or open graph.
      • problemstring
        What's wrong, in English.
      • fixstring
        How to fix it, in English.
  • serp_previewobject
    The page's current title and meta description as Google renders them: the same output as POST /seo/serp-preview without a keyword.
    serp_preview keys(3)SerpPreview
    • previewobject
      The result as searchers would see it on desktop.
      preview keys(3)
      • title_shownstring
        The title as displayed: cut at a word boundary, with ... added, when it's wider than about 580px.
      • description_shownstring
        The description as displayed, cut the same way after about 920px (two lines).
      • breadcrumbstring
        The URL line under the site name: the host, then up to 3 path segments, separated by › .
    • measurementsobject
      Lengths and rendered widths. Widths are approximate pixels, computed from Arial's font metrics.
      measurements keys(3)
      • titleobject
        The title, at the size of a desktop result title.
        title keys(5)
        • charsinteger
          Length in characters.
        • pixelsinteger
          Rendered width in pixels.
        • limit_pixelsinteger
          Google's desktop limit for titles: 580.
        • truncatedboolean
          true when Google would cut it.
        • fontstring
          The font the widths assume: 20px Arial (approx.).
      • descriptionobject
        The meta description, at the size of a result snippet.
        description keys(7)
        • charsinteger
          Length in characters.
        • pixelsinteger
          Rendered width in pixels, on one line.
        • limit_pixelsinteger
          Google's desktop limit, two lines: 920.
        • mobile_limit_pixelsinteger
          Google's mobile limit: 680.
        • truncatedboolean
          true when Google would cut it on desktop.
        • fits_mobileboolean
          true when it fits on mobile too.
        • fontstring
          The font the widths assume: 14px Arial (approx.).
      • urlobject
        The URL.
        url keys(3)
        • charsinteger
          Length in characters.
        • path_depthinteger or null
          Number of path segments (/blog/post/ is 2), or null if the URL can't be parsed.
        • httpsboolean or null
          true for an HTTPS URL, or null if the URL can't be parsed.
    • checksarray of objects
      Ten pass/fail checks, in this order: title_length, title_width, description_length, description_width, keyword_placement, url_readable, https, title_case (not mostly uppercase), title_repetition (no keyword stuffing) and title_vs_description (the description adds to the title). keyword_placement is exact when a keyword is given; otherwise it's informational, comparing the title's lead words with the description.
      checks items(3)SeoCheck
      • checkstring
        Machine-readable name of the check, such as title_width or sitemap_vs_robots.
      • passboolean
        true when the check passes.
      • notestring
        What was measured or found and, on a failure, what to do about it. Always in English.
  • expertobject
    The consultant's review, written by AI in the page's language. A value the model didn't provide is null.
    expert keys(8)
    • verdictstring or null
      The overall verdict, in 2–3 sentences.
    • intent_analysisstring or null
      What searchers want from this page's topic, and whether the content delivers it.
    • strongest_assetstring or null
      What the page already does well.
    • biggest_blockerstring or null
      The one thing holding the page back the most.
    • recommendationsarray of objects
      Prioritized actions, usually 5–8, most important first.
      recommendations items(4)
      • prioritystring or null
        How much it matters.

        One ofhighmediumlow

      • actionstring
        What to do.
      • whystring
        Why it matters (can be empty).
      • effortstring or null
        Rough effort it takes.

        One ofminuteshoursdays

    • suggested_target_keywordstring or null
      The query the page should target.
    • suggested_titlestring or null
      A better title, aimed at 60 characters or less.
    • suggested_meta_descriptionstring or null
      A better meta description, aimed at 160 characters or less.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/analyzeIllustrative

Request body
{
  "url": "https://gladiacteur.com"
}
Response · 200 OK
{
  "page": {
    "url": "https://gladiacteur.com/",
    "final_url": "https://gladiacteur.com/",
    "http_status": 200,
    "https": true,
    "title": "Gladiacteur - IA, Technologie et Business : Outils, Tendances & Transformation Digitale",
    "title_length": 87,
    "meta_description": "Découvrez comment l’IA, les technologies et l’automatisation transforment les entreprises. Tendances, outils, transformation digitale et stratégies business pour améliorer votre croissance.",
    "meta_description_length": 189,
    "canonical": "https://gladiacteur.com/",
    "robots_meta": "follow, index",
    "lang": "fr-FR",
    "viewport": true,
    "charset": true,
    "favicon": true,
    "h1": [],
    "h2": [],
    "h3": [
      "8 Prompts ChatGPT pour votre Business Plan",
      "Outils pour Manager : Suite Complète d’Outils de Gestion Stratégique Gratuits"
    ],
    "word_count": 444,
    "images_total": 28,
    "images_missing_alt": 6,
    "links_internal": 77,
    "links_external": 5,
    "open_graph": {
      "og:locale": "fr_FR",
      "og:type": "website",
      "og:title": "Gladiacteur",
      "og:description": "L'intelligence artificielle peut transformer votre entreprise : automatisation, analyse de données et optimisation des performances.",
      "og:url": "https://gladiacteur.com/",
      "og:site_name": "Gladiacteur"
    },
    "twitter_card": {
      "twitter:card": "summary_large_image",
      "twitter:title": "Gladiacteur",
      "twitter:description": "L'intelligence artificielle peut transformer votre entreprise : automatisation, analyse de données et optimisation des performances."
    },
    "json_ld_types": [
      "Person",
      "WebSite",
      "CollectionPage"
    ],
    "hreflang": [],
    "html_size_bytes": 114615
  },
  "heuristics": {
    "score": 70,
    "issues": [
      {
        "severity": "major",
        "element": "h1",
        "problem": "No <h1> heading.",
        "fix": "Add exactly one <h1> stating the page's topic with the primary keyword."
      },
      {
        "severity": "minor",
        "element": "title",
        "problem": "Title is 87 chars; Google truncates around 60.",
        "fix": "Front-load the keyword and trim to ≤60 characters."
      },
      {
        "severity": "minor",
        "element": "open graph",
        "problem": "Open Graph tags have no og:image, so shares render without a picture.",
        "fix": "Add og:image: an absolute URL to a 1200x630 image under 5 MB."
      }
    ]
  },
  "serp_preview": {
    "preview": {
      "title_shown": "Gladiacteur - IA, Technologie et Business : Outils, Tendances ...",
      "description_shown": "Découvrez comment l’IA, les technologies et l’automatisation transforment les entreprises. Tendances, outils, transformation digitale et stratégies ...",
      "breadcrumb": "gladiacteur.com"
    },
    "measurements": {
      "title": {
        "chars": 87,
        "pixels": 777,
        "limit_pixels": 580,
        "truncated": true,
        "font": "20px Arial (approx.)"
      },
      "description": {
        "chars": 189,
        "pixels": 1160,
        "limit_pixels": 920,
        "mobile_limit_pixels": 680,
        "truncated": true,
        "fits_mobile": false,
        "font": "14px Arial (approx.)"
      },
      "url": {
        "chars": 24,
        "path_depth": 0,
        "https": true
      }
    },
    "checks": [
      {
        "check": "title_width",
        "pass": false,
        "note": "About 777px wide, over the ~580px desktop limit. Searchers will see: \"Gladiacteur - IA, Technologie et Business : Outils, Tendances ...\""
      },
      {
        "check": "description_width",
        "pass": false,
        "note": "About 1160px: cut after ~920px (two desktop lines). On mobile (~680px) it will be cut, so put the key promise first."
      },
      {
        "check": "https",
        "pass": true,
        "note": "Served over HTTPS."
      }
    ]
  },
  "expert": {
    "verdict": "La page d'accueil est un bon hub éditorial (77 liens internes, 13 articles mis en avant), mais elle ne cible aucune requête : ni <h1> ni <h2>, et un title de 87 caractères coupé dans Google. En l'état, elle ne peut se classer que sur la marque.",
    "intent_analysis": "Les requêtes visées (IA en entreprise, outils IA, transformation digitale) sont informationnelles. La page y répond par une liste d'articles sans texte de synthèse : elle aide à naviguer, pas à comprendre le sujet.",
    "strongest_asset": "Le maillage interne vers des articles approfondis sur l'IA en entreprise, avec des données structurées WebSite et CollectionPage déjà en place.",
    "biggest_blocker": "L'absence de <h1> et de texte d'introduction : Google ne sait pas sur quel sujet classer la page.",
    "recommendations": [
      {
        "priority": "high",
        "action": "Ajouter un <h1> unique, par exemple « L'IA au service des entreprises », suivi de 150 à 200 mots d'introduction.",
        "why": "Donne à Google le sujet principal de la page et répond à l'intention dès le haut de page.",
        "effort": "hours"
      },
      {
        "priority": "high",
        "action": "Raccourcir le title à 60 caractères au plus, mot-clé en tête.",
        "why": "À 87 caractères, Google coupe « Transformation Digitale », la partie la plus recherchée.",
        "effort": "minutes"
      }
    ],
    "suggested_target_keyword": "IA en entreprise",
    "suggested_title": "IA en entreprise : outils et stratégies | Gladiacteur",
    "suggested_meta_description": "Outils IA, automatisation et stratégies concrètes : Gladiacteur aide les entreprises à réussir leur transformation digitale et à accélérer leur croissance."
  },
  "analysis_id": "128"
}

page, heuristics and serp_preview were computed by the endpoint's own code from the live gladiacteur.com homepage; expert is illustrative. Lists are shortened: the audit found 6 issues.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyurl is missing (url is required.) or isn't a public http or https URL with a domain name.
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedThe page at url can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry.).

Research keywords for any site

POSThttps://autoranko.com/api/public/v1/seo/keywords

Keyword research without a connected site. The seeds come from keywords, then topic, then the page at url (its title segments and headings, at most 5 phrases), up to 20 in all; seeds_used shows exactly which were sent. In ideas mode (the default) the AI expands them into related long-tail keywords, a mix of informational and commercial searches. In metrics mode it estimates metrics for the seeds themselves.

Each keyword comes with estimated monthly volume, competition, difficulty and cost per click. All numbers are AI estimates (estimated is always true): good for comparing and prioritizing keywords, not exact traffic data. A metric the model didn't return is absent. Use language and country to target a market.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • topicstringOptional
    What you want to rank for, as a phrase. Send at least one of topic, url and keywords.
    Length
    2–300 characters
    Example
    outils IA pour PME
  • urlstring (uri)Optional
    A page to take seed phrases from: its title segments, then its headings, skipping the brand name and generic headings such as Contact. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • keywordsarray of stringsOptional
    Seed keywords (ideas) or the exact keywords to evaluate (metrics): a JSON array of 1–20 non-empty strings, each up to 100 characters.
    Max items
    20
    Example
    ["outils IA","automatisation PME"]
  • modestringOptional
    ideas expands the seeds into related keywords; metrics estimates metrics for the seeds themselves, including the ones taken from topic and url.

    One ofideasmetrics

    Default
    ideas
    Example
    ideas
  • languagestringOptional
    Language of the keywords. Defaults to the page's lang when url is sent. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • countrystringOptional
    The market to estimate for: a country name or code, such as FR or France.
    Max length
    60 characters
    Example
    FR
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/keywords \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "outils IA pour PME",
    "language": "fr",
    "country": "FR"
  }'

Response

200OKKeywords with AI-estimated metrics.

Response bodyapplication/json
  • modestring
    The mode that ran.

    One ofideasmetrics

  • keywordsarray of objects
    Keywords with estimated metrics, without duplicates. A metric the model didn't return is absent.
    keywords items(6)Keyword
    • keywordstring
      The keyword.
    • volumeintegerOptional
      Estimated monthly searches.
    • competitionstringOptional
      Estimated advertiser competition.

      One ofLOWMEDIUMHIGH

    • competition_indexintegerOptional
      Competition on a 0–100 scale.
    • difficultyintegerOptional
      Estimated difficulty of ranking on page one, 0–100.
    • cpcnumberOptional
      Estimated cost per click, in USD.
  • estimatedboolean
    Always true: every metric is an AI estimate.
  • seeds_usedarray of strings
    The seed phrases sent to the AI, at most 20: keywords first, then topic, then phrases from the page at url.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/keywordsIllustrative

Request body
{
  "topic": "outils IA pour PME",
  "language": "fr",
  "country": "FR"
}
Response · 200 OK
{
  "mode": "ideas",
  "keywords": [
    {
      "keyword": "outils ia pour pme",
      "volume": 880,
      "competition": "MEDIUM",
      "competition_index": 54,
      "difficulty": 38,
      "cpc": 2.4
    },
    {
      "keyword": "meilleur outil ia gratuit entreprise",
      "volume": 590,
      "competition": "MEDIUM",
      "competition_index": 47,
      "difficulty": 35,
      "cpc": 1.85
    },
    {
      "keyword": "logiciel ia gestion pme",
      "volume": 320,
      "competition": "HIGH",
      "competition_index": 71,
      "difficulty": 44,
      "cpc": 4.6
    },
    {
      "keyword": "automatiser sa pme avec l'ia",
      "volume": 210,
      "competition": "LOW",
      "competition_index": 28,
      "difficulty": 22,
      "cpc": 2.1
    }
  ],
  "estimated": true,
  "seeds_used": [
    "outils IA pour PME"
  ],
  "analysis_id": "129"
}

The keywords and their metrics are illustrative AI estimates.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyNone of topic, url and keywords was sent (Send at least one of topic, url or keywords.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (keywords accepts at most 20 items.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned no keywords, please retry.).

Write a long-form article

POSThttps://autoranko.com/api/public/v1/seo/article

Writes a complete SEO article without a connected site, in two AI steps: an outline (title, meta description, slug, sections and FAQs), then the full HTML body written from it. Ask for 500–4,000 words (1,600 by default) in the tone and language you need. Tables are used where data helps; no images are added.

The call is synchronous and typically takes 1–3 minutes. The response has everything needed to publish anywhere: title, meta_description, slug and html, plus the outline it was written from. word_count is counted from the HTML, not taken from the model.

Uses two AI calls (outline, then draft) from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's, so the request needs two calls left. Allow 300 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • topicstringRequired
    What the article should be about: a working title, a question or a short brief.
    Length
    3–300 characters
    Example
    Comment automatiser sa prospection B2B avec l'IA en 2026
  • target_keywordstringOptional
    The search query the article should rank for. Without one, the outline picks it.
    Max length
    120 characters
    Example
    automatiser prospection B2B IA
  • word_countintegerOptional
    Target length in words. The result lands close to it rather than exactly on it.
    Default
    1600
    Range
    500–4000
    Example
    1500
  • tonestringOptional
    The voice to write in, in your own words, such as friendly, practical or formal, expert.
    Default
    professional, helpful
    Max length
    120 characters
    Example
    professional, helpful
  • languagestringOptional
    Language to write in. Without it, the AI usually follows the language of topic. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/article \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Comment automatiser sa prospection B2B avec l'\''IA en 2026",
    "target_keyword": "automatiser prospection B2B IA",
    "word_count": 1500,
    "language": "fr"
  }'

Response

200OKThe finished article, with its metadata and outline.

Response bodyapplication/json
  • titlestring
    The article title, from the outline (topic if the outline has none).
  • meta_descriptionstring or null
    SEO meta description (requested under 160 characters), or null if the outline has none.
  • slugstring
    URL slug: lowercase ASCII words joined by hyphens, accents and French elisions removed (l'IA becomes ia), at most 75 characters.
  • target_keywordstring or null
    The primary keyword: the outline's, else the one you sent; null if neither.
  • secondary_keywordsarray of strings
    Related keywords the article works in.
  • outlineobject
    The outline the article was written from: the same AI step and structure as a job's outline. Keys are requested from the model, not guaranteed.
    outline keys(10)JobOutline
    • titlestringOptional
      Article title.
    • meta_descriptionstringOptional
      SEO meta description.
    • slugstringOptional
      Suggested URL slug.
    • target_keywordstringOptional
      Primary keyword.
    • secondary_keywordsarray of stringsOptional
      Related keywords to work into the article.
    • sectionsarray of objectsOptional
      The article structure, in order.
      sections items(4)
      • levelstring
        Heading level.

        One ofh2h3

      • headingstring
        Section heading.
      • descriptionstring
        What the section covers.
      • word_countinteger
        Planned length of the section in words.
    • faqsarray of objectsOptional
      Questions for the FAQ section.
      faqs items(2)
      • questionstring
        The question.
      • answer_briefstring
        The gist of the answer.
    • image_suggestionsarray of objectsOptional
      Image ideas. The first one is meant as the featured image.
      image_suggestions items(2)
      • descriptionstring
        What the image shows.
      • alt_textstring
        Suggested alt text.
    • google_image_queriesarray of stringsOptional
      Search queries for finding matching images.
    • video_querystringOptional
      Search query for a related video.
  • htmlstring
    The article body as HTML: headings start at <h2> (the title is separate), with tables where data helps and no images. Ready to publish under title.
  • word_countinteger
    Words in html, counted by Autoranko rather than reported by the model.
  • reading_time_minutesinteger
    Estimated reading time at 230 words a minute (at least 1).
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/articleIllustrative

Request body
{
  "topic": "Comment automatiser sa prospection B2B avec l'IA en 2026",
  "target_keyword": "automatiser prospection B2B IA",
  "word_count": 1500,
  "language": "fr"
}
Response · 200 OK
{
  "title": "Automatiser sa prospection B2B avec l'IA en 2026 : le guide complet",
  "meta_description": "Automatisez votre prospection B2B avec l'IA : outils, scénarios et bonnes pratiques RGPD pour décrocher plus de rendez-vous qualifiés en 2026.",
  "slug": "automatiser-prospection-b2b-ia",
  "target_keyword": "automatiser prospection B2B IA",
  "secondary_keywords": [
    "prospection B2B automatisée",
    "outils IA de prospection",
    "séquences d'emails personnalisées"
  ],
  "outline": {
    "title": "Automatiser sa prospection B2B avec l'IA en 2026 : le guide complet",
    "meta_description": "Automatisez votre prospection B2B avec l'IA : outils, scénarios et bonnes pratiques RGPD pour décrocher plus de rendez-vous qualifiés en 2026.",
    "slug": "automatiser-prospection-b2b-ia",
    "target_keyword": "automatiser prospection B2B IA",
    "secondary_keywords": [
      "prospection B2B automatisée",
      "outils IA de prospection",
      "séquences d'emails personnalisées"
    ],
    "sections": [
      {
        "level": "h2",
        "heading": "Pourquoi automatiser sa prospection B2B en 2026 ?",
        "description": "Ce que coûte une prospection manuelle, et ce que l'IA change.",
        "word_count": 250
      },
      {
        "level": "h2",
        "heading": "Les 5 étapes pour automatiser sa prospection avec l'IA",
        "description": "Du ciblage à la relance, avec un outil par étape.",
        "word_count": 450
      }
    ],
    "faqs": [
      {
        "question": "L'automatisation de la prospection est-elle compatible avec le RGPD ?",
        "answer_brief": "Oui en B2B, avec un intérêt légitime documenté et un lien de désinscription dans chaque message."
      }
    ],
    "image_suggestions": [
      {
        "description": "Commercial devant un tableau de bord de prospection piloté par l'IA",
        "alt_text": "Tableau de bord de prospection B2B automatisée par l'IA"
      }
    ],
    "google_image_queries": [
      "prospection B2B intelligence artificielle"
    ],
    "video_query": "automatiser sa prospection B2B avec l'IA"
  },
  "html": "<p>Automatiser sa prospection B2B avec l'IA, c'est confier à des outils le ciblage, la personnalisation des messages et les relances, pour que vos commerciaux se concentrent sur les rendez-vous.</p>\n<h2>Pourquoi automatiser sa prospection B2B en 2026 ?</h2>\n<p>Une prospection manuelle repose sur des tâches répétitives : trouver les bons contacts, personnaliser chaque message, relancer au bon moment.</p>\n<!-- … shortened for the docs … -->",
  "word_count": 1563,
  "reading_time_minutes": 7,
  "analysis_id": "141"
}

html is shortened, and outline is abbreviated to show its structure.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodytopic is missing or blank (topic is required.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (word_count must be between 500 and 4000.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the two calls this request needs (Monthly AI call allowance reached (1499/1500 on the starter plan; this endpoint needs 2 calls). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned an incomplete outline, please retry. or The AI returned a truncated article, please retry.).

Write a short article

POSThttps://autoranko.com/api/public/v1/seo/article-short

Writes a short, publication-ready piece of 150–800 words (400 by default): a news post, a product blurb, an FAQ answer or a landing-page section. It answers the query in its first two sentences, then backs the answer up with one or two <h2> sections at most, and a list or small table where it genuinely helps.

html has no <h1> (the title is separate) and no images, ready to drop into a page under title. word_count is counted from the HTML, not taken from the model.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • topicstringRequired
    What the piece should answer or cover: a question, a working title or a short brief.
    Length
    3–300 characters
    Example
    Les 5 erreurs à éviter quand on adopte l'IA en PME
  • target_keywordstringOptional
    The search query the piece should rank for.
    Max length
    120 characters
    Example
    adopter IA PME
  • word_countintegerOptional
    Target length in words. The result lands close to it rather than exactly on it.
    Default
    400
    Range
    150–800
    Example
    400
  • tonestringOptional
    The voice to write in, in your own words, such as friendly, practical or formal, expert.
    Default
    clear, expert, helpful
    Max length
    120 characters
    Example
    clear, expert, helpful
  • languagestringOptional
    Language to write in. Without it, the AI usually follows the language of topic. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/article-short \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Les 5 erreurs à éviter quand on adopte l'\''IA en PME",
    "target_keyword": "adopter IA PME",
    "word_count": 400,
    "language": "fr"
  }'

Response

200OKThe finished piece and its metadata.

Response bodyapplication/json
  • titlestring
    The title (topic if the model returned none).
  • meta_descriptionstring or null
    SEO meta description (requested at 160 characters or less), or null.
  • slugstring
    URL slug: lowercase ASCII words joined by hyphens, at most 75 characters.
  • htmlstring
    The body as HTML, with no <h1> and no images.
  • word_countinteger
    Words in html, counted by Autoranko rather than reported by the model.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/article-shortIllustrative

Request body
{
  "topic": "Les 5 erreurs à éviter quand on adopte l'IA en PME",
  "target_keyword": "adopter IA PME",
  "word_count": 400,
  "language": "fr"
}
Response · 200 OK
{
  "title": "Adopter l'IA en PME : les 5 erreurs à éviter",
  "meta_description": "Adopter l'IA en PME sans faux pas : objectifs flous, données négligées, équipes oubliées. Les 5 erreurs à éviter et comment les corriger.",
  "slug": "adopter-ia-pme-erreurs-a-eviter",
  "html": "<p>Pour adopter l'IA en PME, partez d'un problème métier précis et mesurable, pas de l'outil à la mode. La plupart des échecs viennent de cinq erreurs évitables.</p>\n<h2>Les 5 erreurs les plus fréquentes</h2>\n<ol>\n<li><strong>Commencer par l'outil</strong> plutôt que par le besoin.</li>\n<!-- … shortened for the docs … -->",
  "word_count": 412,
  "analysis_id": "135"
}

html is shortened.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodytopic is missing or blank (topic is required.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (word_count must be between 150 and 800.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned a truncated article, please retry.).

Write title and meta description variants

POSThttps://autoranko.com/api/public/v1/seo/meta-tags

Writes three title tags and three meta descriptions, plus a slug and a focus keyword, for an existing page (url) or a new one (topic). Titles put the keyword first and aim for 60 characters or less; descriptions aim for 160 or less, with the hook in the first 120.

Every variant is measured the way Google renders it, in pixels, so you can see which ones would be cut. With url, the page's current title and description are measured too, for a before/after comparison. html holds the <title> and <meta name="description"> tags for the first variant of each.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • urlstring (uri)Optional
    The existing page to write tags for: its current tags and headings inform the variants, and its current title and description are measured for comparison. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • topicstringOptional
    What a new page is about, when there's no url. With url, it takes precedence over the page's own heading. Send url, topic or both.
    Length
    2–300 characters
    Example
    transformation digitale des PME
  • target_keywordstringOptional
    The search query to put first in the titles.
    Max length
    120 characters
    Example
    transformation digitale PME
  • brandstringOptional
    Your brand name, for titles that end with it.
    Max length
    80 characters
    Example
    Gladiacteur
  • languagestringOptional
    Language of the tags. Defaults to the page's lang when url is sent. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/meta-tags \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://gladiacteur.com",
    "target_keyword": "transformation digitale PME"
  }'

Response

200OKTitle and description variants, measured, with the page's current tags when url was sent.

Response bodyapplication/json
  • titlesarray of strings
    Title variants, best first: usually 3, at most 5. Each puts the keyword first and aims for 60 characters or less.
  • meta_descriptionsarray of strings
    Meta description variants, best first: usually 3, at most 5. Each aims for 160 characters or less, with the hook in the first 120.
  • slugstring
    A URL slug for the page: lowercase ASCII words joined by hyphens.
  • focus_keywordstring or null
    The keyword the variants target: the model's pick, else target_keyword; null if neither.
  • notesstring or null
    One tip specific to this page, or null.
  • measurementsobject
    Every variant measured as Google renders it, in the same order as titles and meta_descriptions.
    measurements keys(2)
    • titlesarray of objects
      One per title variant.
      titles items(6)TitleMeasurement
      • textstring
        The title that was measured.
      • charsinteger
        Length in characters.
      • pixelsinteger
        Approximate rendered width in pixels (20px Arial).
      • limit_pixelsinteger
        Google's desktop limit for titles: 580.
      • truncatedboolean
        true when Google would cut it.
      • shownstring
        The title as displayed, cut with ... where Google would cut it.
    • meta_descriptionsarray of objects
      One per description variant.
      meta_descriptions items(7)DescriptionMeasurement
      • textstring
        The description that was measured.
      • charsinteger
        Length in characters.
      • pixelsinteger
        Approximate rendered width in pixels, on one line (14px Arial).
      • limit_pixelsinteger
        Google's desktop limit, two lines: 920.
      • truncatedboolean
        true when Google would cut it on desktop.
      • fits_mobileboolean
        true when it also fits on mobile (680px).
      • shownstring
        The description as displayed, cut with ... where Google would cut it.
  • currentobject or null
    With url: the page's current tags, measured the same way, for a before/after comparison. null without url.
    current keys(5)
    • urlstring (uri)
      The page's final URL, after redirects.
    • titlestring or null
      The current title, or null if the page has none.
    • meta_descriptionstring or null
      The current meta description, or null if the page has none.
    • title_measurementobject or null
      The current title, measured; null without one.
      title_measurement keys(6)TitleMeasurement
      • textstring
        The title that was measured.
      • charsinteger
        Length in characters.
      • pixelsinteger
        Approximate rendered width in pixels (20px Arial).
      • limit_pixelsinteger
        Google's desktop limit for titles: 580.
      • truncatedboolean
        true when Google would cut it.
      • shownstring
        The title as displayed, cut with ... where Google would cut it.
    • meta_description_measurementobject or null
      The current meta description, measured; null without one.
      meta_description_measurement keys(7)DescriptionMeasurement
      • textstring
        The description that was measured.
      • charsinteger
        Length in characters.
      • pixelsinteger
        Approximate rendered width in pixels, on one line (14px Arial).
      • limit_pixelsinteger
        Google's desktop limit, two lines: 920.
      • truncatedboolean
        true when Google would cut it on desktop.
      • fits_mobileboolean
        true when it also fits on mobile (680px).
      • shownstring
        The description as displayed, cut with ... where Google would cut it.
  • htmlstring
    The <title> and <meta name="description"> tags for the first variant of each, HTML-escaped and ready to paste into <head>.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/meta-tagsIllustrative

Request body
{
  "url": "https://gladiacteur.com",
  "target_keyword": "transformation digitale PME"
}
Response · 200 OK
{
  "titles": [
    "Transformation digitale PME : outils IA et stratégies",
    "IA et transformation digitale des PME | Gladiacteur"
  ],
  "meta_descriptions": [
    "Transformation digitale PME : outils IA, automatisation et stratégies concrètes pour gagner du temps et accélérer votre croissance.",
    "Outils IA, automatisation, tendances : Gladiacteur aide les PME à réussir leur transformation digitale, avec des guides et des cas concrets."
  ],
  "slug": "transformation-digitale-pme",
  "focus_keyword": "transformation digitale PME",
  "notes": "Ajoutez un <h1> reprenant « transformation digitale PME » : la page d'accueil n'en a aucun.",
  "measurements": {
    "titles": [
      {
        "text": "Transformation digitale PME : outils IA et stratégies",
        "chars": 53,
        "pixels": 455,
        "limit_pixels": 580,
        "truncated": false,
        "shown": "Transformation digitale PME : outils IA et stratégies"
      },
      {
        "text": "IA et transformation digitale des PME | Gladiacteur",
        "chars": 51,
        "pixels": 449,
        "limit_pixels": 580,
        "truncated": false,
        "shown": "IA et transformation digitale des PME | Gladiacteur"
      }
    ],
    "meta_descriptions": [
      {
        "text": "Transformation digitale PME : outils IA, automatisation et stratégies concrètes pour gagner du temps et accélérer votre croissance.",
        "chars": 131,
        "pixels": 809,
        "limit_pixels": 920,
        "truncated": false,
        "fits_mobile": false,
        "shown": "Transformation digitale PME : outils IA, automatisation et stratégies concrètes pour gagner du temps et accélérer votre croissance."
      },
      {
        "text": "Outils IA, automatisation, tendances : Gladiacteur aide les PME à réussir leur transformation digitale, avec des guides et des cas concrets.",
        "chars": 140,
        "pixels": 857,
        "limit_pixels": 920,
        "truncated": false,
        "fits_mobile": false,
        "shown": "Outils IA, automatisation, tendances : Gladiacteur aide les PME à réussir leur transformation digitale, avec des guides et des cas concrets."
      }
    ]
  },
  "current": {
    "url": "https://gladiacteur.com/",
    "title": "Gladiacteur - IA, Technologie et Business : Outils, Tendances & Transformation Digitale",
    "meta_description": "Découvrez comment l’IA, les technologies et l’automatisation transforment les entreprises. Tendances, outils, transformation digitale et stratégies business pour améliorer votre croissance.",
    "title_measurement": {
      "text": "Gladiacteur - IA, Technologie et Business : Outils, Tendances & Transformation Digitale",
      "chars": 87,
      "pixels": 777,
      "limit_pixels": 580,
      "truncated": true,
      "shown": "Gladiacteur - IA, Technologie et Business : Outils, Tendances ..."
    },
    "meta_description_measurement": {
      "text": "Découvrez comment l’IA, les technologies et l’automatisation transforment les entreprises. Tendances, outils, transformation digitale et stratégies business pour améliorer votre croissance.",
      "chars": 189,
      "pixels": 1160,
      "limit_pixels": 920,
      "truncated": true,
      "fits_mobile": false,
      "shown": "Découvrez comment l’IA, les technologies et l’automatisation transforment les entreprises. Tendances, outils, transformation digitale et stratégies ..."
    }
  },
  "html": "<title>Transformation digitale PME : outils IA et stratégies</title>\n<meta name=\"description\" content=\"Transformation digitale PME : outils IA, automatisation et stratégies concrètes pour gagner du temps et accélérer votre croissance.\">",
  "analysis_id": "130"
}

The variants are illustrative and shortened to 2 of 3; every measurement, including current, was computed by the endpoint's own code.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyNeither url nor topic was sent (Send url (to optimize an existing page) or topic (for a new page).).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (brand is too long (max 80 characters).).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry.).

Generate Open Graph and Twitter tags

POSThttps://autoranko.com/api/public/v1/seo/open-graph

Generates a page's social-sharing tags: every Open Graph tag (og:title, og:description, og:type, og:url, og:site_name, og:image, og:image:alt and og:locale) and the Twitter card, plus a ready-to-paste block of <meta> tags.

Facts beat the model: og:url is the page's canonical URL, and og:image only ever comes from image_url or the page's existing og:image, never invented. Whatever stays empty is listed in missing, and image_brief describes the 1200×630 image to create when there's none.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • urlstring (uri)Optional
    The page to tag: its title, description, canonical and existing social tags are used. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • topicstringOptional
    What a new page is about, when there's no url. Send url, topic or both.
    Length
    2–300 characters
    Example
    transformation digitale des PME
  • brandstringOptional
    Your brand name. It becomes og:site_name, overriding the model and the page.
    Max length
    80 characters
    Example
    Gladiacteur
  • image_urlstring (uri)Optional
    The share image, ideally 1200×630: an absolute http or https URL, used as is (it isn't fetched). Without it, the page's existing og:image is kept; none is ever invented.
    Max length
    2048 characters
    Example
    https://gladiacteur.com/images/partage-ia.png
  • languagestringOptional
    Language of the tags. Defaults to the page's lang when url is sent. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/open-graph \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://gladiacteur.com"
  }'

Response

200OKThe final tags, the ready-to-paste block and what's still missing.

Response bodyapplication/json
  • ogobject
    The Open Graph tags. Every key is always present; one that couldn't be filled is an empty string.
    og keys(8)
    • og:titlestring
      Share title, aimed at 70 characters or less; falls back to the page title or topic.
    • og:descriptionstring
      Share description, aimed at 200 characters or less; falls back to the page's meta description.
    • og:typestring
      The object type; anything unrecognized becomes website.

      One ofwebsitearticleproductprofilebookvideo.movievideo.othermusic.songbusiness.business

    • og:urlstring
      The page's canonical URL, or its final URL when it has no valid canonical. Empty without url.
    • og:site_namestring
      brand if sent, else the model's value, else the page's existing one.
    • og:imagestring
      image_url if sent, else the page's existing og:image made absolute. Never invented: empty when neither exists.
    • og:image:altstring
      Alt text for the share image.
    • og:localestring
      Such as fr_FR: the model's value when it's well-formed, else derived from the page's lang.
  • twitterobject
    The Twitter (X) card tags.
    twitter keys(3)
    • twitter:cardstring
      The card type: summary_large_image unless the model chose summary.

      One ofsummary_large_imagesummary

    • twitter:titlestring
      Card title; falls back to og:title.
    • twitter:descriptionstring
      Card description; falls back to og:description.
  • htmlstring
    The ready-to-paste block: one <meta> tag per non-empty value of og and twitter, HTML-escaped (og:image:alt only with an og:image).
  • missingarray of strings
    Keys of og that are still empty, such as og:image when neither image_url nor the page provides one.
  • image_briefstring or null
    One sentence describing the ideal 1200×630 share image to create, or null.
  • currentobject or null
    With url: the page's existing tags, for comparison. null without url.
    current keys(2)
    • open_graphobject
      Every og:* meta tag on the page, keyed by property.
    • twitterobject
      Every twitter:* meta tag on the page, keyed by name.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/open-graphIllustrative

Request body
{
  "url": "https://gladiacteur.com"
}
Response · 200 OK
{
  "og": {
    "og:title": "Gladiacteur : l'IA au service de votre entreprise",
    "og:description": "Outils IA, automatisation et stratégies concrètes pour réussir la transformation digitale de votre entreprise.",
    "og:type": "website",
    "og:url": "https://gladiacteur.com/",
    "og:site_name": "Gladiacteur",
    "og:image": "",
    "og:image:alt": "Tableau de bord d'IA illustrant la transformation digitale d'une entreprise",
    "og:locale": "fr_FR"
  },
  "twitter": {
    "twitter:card": "summary_large_image",
    "twitter:title": "Gladiacteur : l'IA au service de votre entreprise",
    "twitter:description": "Outils IA, automatisation et stratégies pour la transformation digitale."
  },
  "html": "<meta property=\"og:title\" content=\"Gladiacteur : l'IA au service de votre entreprise\">\n<meta property=\"og:description\" content=\"Outils IA, automatisation et stratégies concrètes pour réussir la transformation digitale de votre entreprise.\">\n<meta property=\"og:type\" content=\"website\">\n<meta property=\"og:url\" content=\"https://gladiacteur.com/\">\n<meta property=\"og:site_name\" content=\"Gladiacteur\">\n<meta property=\"og:locale\" content=\"fr_FR\">\n<meta name=\"twitter:card\" content=\"summary_large_image\">\n<meta name=\"twitter:title\" content=\"Gladiacteur : l'IA au service de votre entreprise\">\n<meta name=\"twitter:description\" content=\"Outils IA, automatisation et stratégies pour la transformation digitale.\">",
  "missing": [
    "og:image"
  ],
  "image_brief": "Un visuel 1200×630 : un tableau de bord d'IA stylisé sur fond bleu nuit, le logo Gladiacteur en bas à droite, sans texte superflu.",
  "current": {
    "open_graph": {
      "og:locale": "fr_FR",
      "og:type": "website",
      "og:title": "Gladiacteur",
      "og:description": "L'intelligence artificielle peut transformer votre entreprise : automatisation, analyse de données et optimisation des performances.",
      "og:url": "https://gladiacteur.com/",
      "og:site_name": "Gladiacteur"
    },
    "twitter": {
      "twitter:card": "summary_large_image",
      "twitter:title": "Gladiacteur",
      "twitter:description": "L'intelligence artificielle peut transformer votre entreprise : automatisation, analyse de données et optimisation des performances."
    }
  },
  "analysis_id": "131"
}

The page has no share image, so og:image stays empty and is listed in missing. html, missing and current were computed by the endpoint's own code from the model's illustrative values.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyNeither url nor topic was sent (Send url (to tag an existing page) or topic (for a new page).).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (image_url must be an http(s) URL.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry.).

Generate JSON-LD structured data

POSThttps://autoranko.com/api/public/v1/seo/schema

Generates valid schema.org JSON-LD for one of eight types: article, faq, local_business, product, organization, breadcrumb, howto or website. Pass the facts in details, give a url to read them from the page, or both.

The markup uses only the facts you give. A required fact that's missing becomes a TODO: … string listed in todo_paths, never an invented rating or address. google is a fixed reference of what Google requires and recommends for the type, and whether it still earns a rich result. With url, duplicate_warning flags a type the page already marks up.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • schema_typestringRequired
    The kind of markup to generate. schema.org names work too, such as LocalBusiness, FAQPage, BlogPosting, NewsArticle, BreadcrumbList or HowTo.

    One ofarticlefaqlocal_businessproductorganizationbreadcrumbhowtowebsite

    Max length
    40 characters
    Example
    organization
  • detailsobjectOptional
    The facts to mark up, as a JSON object of up to 20,000 characters with any keys: names, URLs, address, opening hours, prices, questions and answers. Required unless url is sent. Only these facts and the page's are used: a missing required fact becomes a TODO: … string rather than an invention.
  • urlstring (uri)Optional
    A page to read facts from as well: its title, description, headings, canonical, Open Graph tags and the JSON-LD types it already has. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/schema \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_type": "organization",
    "url": "https://gladiacteur.com"
  }'

Response

200OKThe JSON-LD, its <script> block, what's missing and Google's requirements for the type.

Response bodyapplication/json
  • schema_typestring
    The type generated, normalized: local_business for LocalBusiness, for example.

    One ofarticlefaqlocal_businessproductorganizationbreadcrumbhowtowebsite

  • json_ldobject
    The JSON-LD, built only from details and the page, with @context on every top-level node. A required fact that's missing is a TODO: … string. Usually one object; an array of objects when the markup needs several nodes.
  • htmlstring
    json_ld as a ready-to-paste <script type="application/ld+json"> block, with < escaped so the block can't be broken out of.
  • missing_fieldsarray of strings
    Fields Google requires or recommends that the input didn't provide.
  • todo_pathsarray of strings
    Paths of the TODO: … placeholders in json_ld, such as address.streetAddress or sameAs[0]. Replace them before publishing.
  • validation_notesstring or null
    The model's notes on validity and rich-result eligibility, or null.
  • googleobject
    What Google documents for the type: a fixed reference, not generated.
    google keys(4)
    • schema_org_typestring
      The schema.org type to use, such as Organization.
    • google_requiredarray of strings
      Properties Google requires.
    • google_recommendedarray of strings
      Properties Google recommends.
    • rich_resultstring
      What the markup earns in Google today, including retired rich results (HowTo, and FAQ outside government and health sites).
  • existing_on_pagearray of strings or null
    With url: the @type values the page already marks up. null without url.
  • duplicate_warningstring or null
    Set when the page already marks up a type this markup generates (often from a CMS or SEO plugin): replace or merge that block rather than adding a second one. null otherwise.
  • validate_witharray of strings
    Where to test the markup: Google's Rich Results Test and the Schema.org validator.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/schemaIllustrative

Request body
{
  "schema_type": "organization",
  "details": {
    "name": "Gladiacteur",
    "url": "https://gladiacteur.com",
    "description": "IA, technologie et business: outils et transformation digitale"
  }
}
Response · 200 OK
{
  "schema_type": "organization",
  "json_ld": {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Gladiacteur",
    "url": "https://gladiacteur.com",
    "description": "IA, technologie et business: outils et transformation digitale",
    "logo": "TODO: URL of the logo (square, at least 112x112 px)",
    "sameAs": [
      "TODO: URLs of the official social profiles"
    ]
  },
  "html": "<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Organization\",\n  \"name\": \"Gladiacteur\",\n  \"url\": \"https://gladiacteur.com\",\n  \"description\": \"IA, technologie et business: outils et transformation digitale\",\n  \"logo\": \"TODO: URL of the logo (square, at least 112x112 px)\",\n  \"sameAs\": [\n    \"TODO: URLs of the official social profiles\"\n  ]\n}\n</script>",
  "missing_fields": [
    "logo",
    "sameAs",
    "contactPoint"
  ],
  "todo_paths": [
    "logo",
    "sameAs[0]"
  ],
  "validation_notes": "Valid Organization markup. Fill in logo and sameAs before publishing, and place it on the homepage only.",
  "google": {
    "schema_org_type": "Organization",
    "google_required": [],
    "google_recommended": [
      "name",
      "url",
      "logo",
      "sameAs",
      "contactPoint"
    ],
    "rich_result": "Helps Google's knowledge panel and the logo it shows. Place it on the homepage, with sameAs pointing to your official profiles."
  },
  "existing_on_page": null,
  "duplicate_warning": null,
  "validate_with": [
    "https://search.google.com/test/rich-results",
    "https://validator.schema.org/"
  ],
  "analysis_id": "133"
}

The logo and social profiles weren't in details, so they're TODO placeholders. html, todo_paths and google were computed by the endpoint's own code.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyschema_type is missing (schema_type is required.) or isn't one of the eight types (schema_type must be one of: article, faq, local_business, product, organization, breadcrumb, howto, website.).
400invalid_bodyNeither details nor url was sent (details is required (an object with the facts to mark up), unless url is given to read them from the page.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (details is too large (max 20000 characters of JSON).).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned invalid JSON-LD, please retry.).

Plan the heading structure

POSThttps://autoranko.com/api/public/v1/seo/headings

Designs the heading structure that best serves a query: one <h1>, <h2> sections in search-intent order (the answer first, depth after), <h3> subsections only where a section genuinely splits, and 3–5 questions for an FAQ block.

Send topic for a new page. Send url to restructure an existing one: its current headings are improved rather than replaced blindly, and come back in current for comparison. html lays the structure out as headings, ready to fill in.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • topicstringOptional
    What a new page is about. Send topic, url or both.
    Length
    2–300 characters
    Example
    outils IA pour entreprise
  • urlstring (uri)Optional
    An existing page to restructure: its current headings are improved rather than replaced blindly. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • target_keywordstringOptional
    The search query the page should rank for.
    Max length
    120 characters
    Example
    outils IA pour entreprise
  • languagestringOptional
    Language of the headings. Defaults to the page's lang when url is sent. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/headings \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://gladiacteur.com",
    "target_keyword": "outils IA pour entreprise"
  }'

Response

200OKThe recommended headings, as data and as HTML.

Response bodyapplication/json
  • h1string
    The recommended <h1>.
  • outlinearray of objects
    The <h2> and <h3> structure in reading order: the answer first, depth after.
    outline items(3)
    • levelstring
      Heading level. The first item is always h2.

      One ofh2h3

    • headingstring
      The heading text.
    • coversstring
      What belongs in the section, in one line (can be empty).
  • faq_candidatesarray of strings
    3–5 questions worth answering in an FAQ block.
  • htmlstring
    h1 and outline as HTML headings, one per line with <h3> indented, escaped and ready to fill in.
  • currentobject or null
    With url: the page's current headings (at most 25 per level), for comparison. null without url.
    current keys(3)
    • h1array of strings
      Current <h1> headings.
    • h2array of strings
      Current <h2> headings.
    • h3array of strings
      Current <h3> headings.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/headingsIllustrative

Request body
{
  "url": "https://gladiacteur.com",
  "target_keyword": "outils IA pour entreprise"
}
Response · 200 OK
{
  "h1": "Outils IA pour entreprise : automatiser, décider, grandir",
  "outline": [
    {
      "level": "h2",
      "heading": "Quels outils IA pour votre entreprise en 2026 ?",
      "covers": "La réponse directe : les grandes familles d'outils et leur usage."
    },
    {
      "level": "h3",
      "heading": "Automatiser les tâches répétitives",
      "covers": "Prospection, facturation, support client."
    },
    {
      "level": "h3",
      "heading": "Mieux décider grâce aux données",
      "covers": "Analyse de données et intelligence économique."
    },
    {
      "level": "h2",
      "heading": "Comment choisir un outil IA ?",
      "covers": "Coût, intégration, données, RGPD."
    },
    {
      "level": "h2",
      "heading": "Exemples concrets en PME",
      "covers": "Cas d'usage chiffrés, avec liens vers les articles du site."
    }
  ],
  "faq_candidates": [
    "Quel est le meilleur outil IA gratuit pour une PME ?",
    "Combien coûte l'intégration de l'IA en entreprise ?",
    "L'IA est-elle compatible avec le RGPD ?"
  ],
  "html": "<h1>Outils IA pour entreprise : automatiser, décider, grandir</h1>\n<h2>Quels outils IA pour votre entreprise en 2026 ?</h2>\n  <h3>Automatiser les tâches répétitives</h3>\n  <h3>Mieux décider grâce aux données</h3>\n<h2>Comment choisir un outil IA ?</h2>\n<h2>Exemples concrets en PME</h2>",
  "current": {
    "h1": [],
    "h2": [],
    "h3": [
      "8 Prompts ChatGPT pour votre Business Plan",
      "Outils pour Manager : Suite Complète d’Outils de Gestion Stratégique Gratuits"
    ]
  },
  "analysis_id": "132"
}

The headings are illustrative. html and current were computed by the endpoint's own code; current.h3 is shortened (the page has 13).

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyNeither topic nor url was sent (Send topic (for a new page) or url (to restructure an existing page).).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (topic must be at least 2 characters.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry.).

Create a content brief

POSThttps://autoranko.com/api/public/v1/seo/content-brief

Writes a brief a writer can work from for one keyword, the way the search results see it: the intent that wins, the angle a new page can own, the target length, the questions to answer, the entities to cover, a section structure, internal-link ideas, and a title and meta description.

Describe your business or audience in context to tailor the angle. A field the model leaves out comes back as null, or as an empty list.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • keywordstringRequired
    The search query the page will target.
    Length
    2–150 characters
    Example
    automatisation des processus métier
  • contextstringOptional
    Who the page is for, in your own words: your business, offer, audience or constraints. It shapes the angle and the internal-link ideas.
    Max length
    4000 characters
    Example
    Blog français sur l'IA et la transformation digitale des PME
  • languagestringOptional
    Language of the brief. Without it, the AI usually follows the language of keyword. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/content-brief \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "automatisation des processus métier",
    "context": "Blog français sur l'\''IA et la transformation digitale des PME",
    "language": "fr"
  }'

Response

200OKThe brief.

Response bodyapplication/json
  • keywordstring
    The keyword the brief is for.
  • search_intentstring or null
    The intent the search results reward, or null.

    One ofinformationalcommercialtransactionalnavigational

  • intent_notesstring or null
    What the top results have in common, and what that means for the page.
  • target_word_countinteger or null
    Recommended length in words.
  • audiencestring or null
    Who the page is for.
  • anglestring or null
    The differentiating take a new page can own.
  • must_answer_questionsarray of strings
    Questions the page must answer (5–8 requested).
  • entities_to_coverarray of strings
    Terms and concepts to cover (8–12 requested).
  • suggested_structurearray of objects
    Sections, in order.
    suggested_structure items(2)
    • headingstring
      Section heading.
    • notesstring
      What the section should do (can be empty).
  • internal_link_ideasarray of strings
    Topics worth linking to or from.
  • title_suggestionstring or null
    A title for the page.
  • meta_description_suggestionstring or null
    A meta description for the page.
  • success_metricstring or null
    What ranking well looks like for this query.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/content-briefIllustrative

Request body
{
  "keyword": "automatisation des processus métier",
  "context": "Blog français sur l'IA et la transformation digitale des PME",
  "language": "fr"
}
Response · 200 OK
{
  "keyword": "automatisation des processus métier",
  "search_intent": "informational",
  "intent_notes": "Les premiers résultats sont des guides : une définition, des exemples par service, puis des outils. Les pages produit des éditeurs arrivent plus bas.",
  "target_word_count": 1800,
  "audience": "Dirigeants et responsables des opérations de PME qui veulent réduire les tâches manuelles.",
  "angle": "Une méthode en 5 étapes pour choisir les premiers processus à automatiser, avec le gain de temps estimé pour chacun.",
  "must_answer_questions": [
    "Qu'est-ce que l'automatisation des processus métier ?",
    "Quels processus automatiser en premier dans une PME ?",
    "Quelle différence entre RPA et automatisation par l'IA ?"
  ],
  "entities_to_cover": [
    "RPA",
    "workflow",
    "BPM",
    "ERP",
    "intelligence artificielle"
  ],
  "suggested_structure": [
    {
      "heading": "Définition et enjeux pour une PME",
      "notes": "Réponse directe en deux phrases, puis les gains attendus."
    },
    {
      "heading": "Quels processus automatiser en premier ?",
      "notes": "Grille de priorisation : volume, répétitivité, risque d'erreur."
    }
  ],
  "internal_link_ideas": [
    "10 outils IA pour automatiser son business",
    "Usage de l'IA en entreprise"
  ],
  "title_suggestion": "Automatisation des processus métier : le guide pour les PME",
  "meta_description_suggestion": "Quels processus automatiser en premier, avec quels outils et pour quel gain ? La méthode en 5 étapes pour automatiser les processus métier d'une PME.",
  "success_metric": "Top 5 sur la requête et ses variantes (« automatiser les processus », « automatisation BPM ») en 3 à 6 mois.",
  "analysis_id": "134"
}

The lists are shortened.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodykeyword is missing or blank (keyword is required.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (context is too long (max 4000 characters).).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry.).

Rewrite copy for SEO

POSThttps://autoranko.com/api/public/v1/seo/rewrite

Rewrites any copy, from a paragraph to a full article, to rank for target_keyword and read better: tighter sentences, concrete claims, natural keyword use and a scannable structure. Facts and HTML tags are kept, and plain text stays plain text. Steer it with instructions.

metrics compares word count and keyword density before and after, measured by Autoranko on the text itself rather than reported by the model. Long inputs, up to 30,000 characters, can take a few minutes.

Uses one AI call from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month), not from a site's. Allow 300 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • contentstringRequired
    The copy to rewrite, as plain text or HTML: a paragraph, a landing-page section or a full article.
    Length
    10–30000 characters
    Example
    Notre site parle de IA et technologie. Nous avons des articles sur le business et les outils. Lisez nos articles pour en savoir plus sur la transformation digitale.
  • target_keywordstringOptional
    The search query the copy should rank for. It's also what metrics counts.
    Max length
    120 characters
    Example
    transformation digitale
  • instructionsstringOptional
    Extra directions, in your own words, such as a length, a tone or a term to avoid.
    Max length
    2000 characters
    Example
    Keep it under 60 words.
  • languagestringOptional
    Language to write in. Without it, the AI usually keeps the language of content. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/rewrite \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Notre site parle de IA et technologie. Nous avons des articles sur le business et les outils. Lisez nos articles pour en savoir plus sur la transformation digitale.",
    "target_keyword": "transformation digitale",
    "language": "fr"
  }'

Response

200OKThe rewrite, a summary of the changes and before/after metrics.

Response bodyapplication/json
  • htmlstring
    The rewritten copy, in the same format as content: HTML tags are kept, and plain text stays plain text.
  • changes_summaryarray of strings
    What changed, in 3–6 points.
  • keyword_density_notestring or null
    The model's comment on keyword use, or null.
  • metricsobject
    Word count and keyword density, measured by Autoranko on the text itself (HTML tags ignored).
    metrics keys(2)
    • beforeobject
      content as sent.
      before keys(3)TextStats
      • wordsinteger
        Words in the text, HTML tags ignored.
      • keyword_occurrencesinteger or null
        Times target_keyword appears as a whole phrase (case and accents ignored), or null without a target_keyword.
      • keyword_density_pctnumber or null
        Share of the words taken by those occurrences, as a percentage with up to 2 decimals, or null without a target_keyword.
    • afterobject
      The rewrite.
      after keys(3)TextStats
      • wordsinteger
        Words in the text, HTML tags ignored.
      • keyword_occurrencesinteger or null
        Times target_keyword appears as a whole phrase (case and accents ignored), or null without a target_keyword.
      • keyword_density_pctnumber or null
        Share of the words taken by those occurrences, as a percentage with up to 2 decimals, or null without a target_keyword.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/rewriteIllustrative

Request body
{
  "content": "Notre site parle de IA et technologie. Nous avons des articles sur le business et les outils. Lisez nos articles pour en savoir plus sur la transformation digitale.",
  "target_keyword": "transformation digitale",
  "language": "fr"
}
Response · 200 OK
{
  "html": "Réussissez votre transformation digitale grâce à nos articles sur l'IA, la technologie et le business. Comparatifs d'outils, méthodes pas à pas et cas concrets : tout pour passer de l'idée à l'action. Commencez par nos guides sur la transformation digitale.",
  "changes_summary": [
    "Mot-clé « transformation digitale » placé dès la première phrase.",
    "Promesses concrètes : comparatifs d'outils, méthodes pas à pas, cas réels.",
    "Appel à l'action plus précis en fin de texte."
  ],
  "keyword_density_note": "2 occurrences sur 39 mots : normal pour un texte aussi court, mais visez 1 à 2 % sur une page complète.",
  "metrics": {
    "before": {
      "words": 28,
      "keyword_occurrences": 1,
      "keyword_density_pct": 7.14
    },
    "after": {
      "words": 39,
      "keyword_occurrences": 2,
      "keyword_density_pct": 10.26
    }
  },
  "analysis_id": "136"
}

The rewrite is illustrative; metrics was computed by the endpoint's own code.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodycontent is missing or blank (content is required.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (content is too long (max 30000 characters).).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe account's monthly AI-call allowance can't cover the call this request needs (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). It's checked before the body is read.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned an empty rewrite, please retry.).

Write image alt text

POSThttps://autoranko.com/api/public/v1/seo/alt-texts

Writes alt text for each image in images. Send each image's file name and the text around it, or its purpose, for the most specific results. Every alt comes with its length, lint warnings and a ready <img> tag; a purely decorative image gets an empty alt.

Add url to give the AI the page as shared context. A URL alone can't reveal each image's file and surroundings, so with only url the endpoint makes no AI call: it returns the page's image counts, the guidelines and a note, and alt_texts is empty.

Uses one AI call when images is sent, from the account's monthly AI-call allowance (Free 300, Starter 1,500, Pro 6,000 AI calls per calendar month); with url alone it makes none. Allow 120 seconds before your HTTP client times out.

Request

Body parametersapplication/json
  • imagesarrayOptional
    The images to describe: 1–30 objects with context (required, up to 1,000 characters: the text around the image, or what it's for) and filename (optional, up to 300 characters: the file name or URL, which sharpens the alt and gets you a ready <img> tag). Sending images makes one AI call. Send images, url or both.
  • urlstring (uri)Optional
    The page the images are on, as shared context. Sent alone, it returns the page's image counts and the guidelines, with no AI call. Any public http or https URL; a bare host such as gladiacteur.com gets https:// added. At most 3 redirects are followed, and the page must answer within 15 seconds with a status below 400.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • target_keywordstringOptional
    Used only where an image genuinely shows it: keyword-stuffed alt text is a spam signal.
    Max length
    120 characters
    Example
    tableau de bord IA
  • languagestringOptional
    Language of the alt text. Defaults to the page's lang when url is sent. Send a language name or code, such as fr, fr-FR or French.
    Length
    2–40 characters
    Example
    fr
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/alt-texts \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "context": "Illustration d'\''un tableau de bord IA analysant des données business",
        "filename": "dashboard-ia.png"
      }
    ]
  }'

Response

200OKAn alt text per image, or the page's image counts when only url was sent.

Response bodyapplication/json
  • alt_textsarray of objects
    One entry per item of images, in the same order. Empty when only url was sent.
    alt_texts items(8)
    • filenamestring or null
      The filename you sent, or null.
    • contextstring
      The context you sent.
    • altstring
      The alt text, aimed at 125 characters or less. Empty for a decorative image.
    • decorativeboolean
      true for a purely decorative image: give it alt="" so screen readers skip it.
    • reasonstring or null
      Why this alt text, or null.
    • lengthinteger
      Characters in alt.
    • warningsarray of strings
      Lint warnings, in English: an empty alt on an image that isn't decorative, over 125 characters, an image of … opening, or a generic or underscored file name.
    • htmlstring or null
      A ready <img> tag (src is the filename) when a file name was sent, else null.
  • pageobject or null
    With url: the page's image counts. null without url.
    page keys(4)
    • urlstring (uri)
      The page's final URL, after redirects.
    • titlestring or null
      The page title, or null.
    • images_totalinteger
      Number of <img> tags.
    • images_missing_altinteger
      <img> tags whose alt text is missing or empty.
  • guidelinesarray of strings
    Alt-text best practices, in English: always the same 9 rules.
  • notestring or null
    With only url: the page's image counts and how to get a specific alt for each image. null when images was sent.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/alt-textsIllustrative

Request body
{
  "images": [
    {
      "context": "Illustration d'un tableau de bord IA analysant des données business",
      "filename": "dashboard-ia.png"
    },
    {
      "context": "Photo de l'équipe lors d'un atelier sur l'IA générative",
      "filename": "IMG_0042.jpg"
    }
  ]
}
Response · 200 OK
{
  "alt_texts": [
    {
      "filename": "dashboard-ia.png",
      "context": "Illustration d'un tableau de bord IA analysant des données business",
      "alt": "Tableau de bord d'IA analysant des données business sous forme de graphiques",
      "decorative": false,
      "reason": "Décrit ce que montre l'illustration, dans le contexte business de la page.",
      "length": 76,
      "warnings": [],
      "html": "<img src=\"dashboard-ia.png\" alt=\"Tableau de bord d'IA analysant des données business sous forme de graphiques\">"
    },
    {
      "filename": "IMG_0042.jpg",
      "context": "Photo de l'équipe lors d'un atelier sur l'IA générative",
      "alt": "Équipe réunie autour d'un écran pendant un atelier sur l'IA générative",
      "decorative": false,
      "reason": "Précise la scène et le sujet de l'atelier, sans bourrage de mots-clés.",
      "length": 70,
      "warnings": [
        "The filename is generic. Rename it descriptively with hyphens before uploading."
      ],
      "html": "<img src=\"IMG_0042.jpg\" alt=\"Équipe réunie autour d'un écran pendant un atelier sur l'IA générative\">"
    }
  ],
  "page": null,
  "guidelines": [
    "Describe what the image shows, specifically: the subject, the action and the detail that matters on this page. Keep it under ~125 characters.",
    "Skip \"image of\" and \"photo of\": screen readers already announce that it is an image."
  ],
  "note": null,
  "analysis_id": "137"
}

The alt texts are illustrative; length, warnings and html were computed by the endpoint's own code. guidelines is shortened: it always lists the same 9 rules.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodyNeither images nor url was sent (Send images (a list of {context, filename?}; best results) or url (page-level audit and guidelines).).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (images[0].context is required.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
422fetch_failedurl was sent, and the page can't be fetched: the domain doesn't resolve, the server doesn't answer within 15 seconds, the host is private, or the page answers with a status of 400 or more. message names the URL and the reason.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitimages was sent and the account's monthly AI-call allowance can't cover the call (Monthly AI call allowance reached (300/300 on the free plan). Upgrade at https://autoranko.com/pricing or wait for next month.). With url alone, no allowance is needed.
502upstream_errorThe AI request failed (The AI request failed, please retry.) or its result was unusable (The AI returned an incomplete result, please retry. or The AI returned no alt texts, please retry.).

Generate robots.txt and a sitemap

POSThttps://autoranko.com/api/public/v1/seo/robots-sitemap

Builds a robots.txt and an XML sitemap for a site from the pages you list: exact and correctly escaped for 1 URL or 500, with duplicates removed. Pages without priority or changefreq get defaults from their path.

checks reviews the result for crawl problems: sitemap URLs blocked by your own Disallow rules, blocked CSS or JavaScript, utility pages (login, cart, search), query strings, inconsistent trailing slashes and missing lastmod dates. instructions says where to upload each file and how to submit the sitemap.

Pure computation: no AI call and nothing counted against the AI-call allowance, so only the rate limit applies.

Request

Body parametersapplication/json
  • site_urlstring (uri)Required
    The site's home URL. Only its origin is used: every URL in the sitemap is on this host and uses its scheme. It isn't fetched.
    Max length
    2048 characters
    Example
    https://gladiacteur.com
  • pagesarrayRequired
    The pages to list: 1–500 objects with path (required: a path such as /contact/, or an absolute URL on the same host), and optionally priority (a number from 0 to 1), changefreq (one of always, hourly, daily, weekly, monthly, yearly, never) and lastmod (the date the page last changed meaningfully, YYYY-MM-DD or an ISO 8601 date-time, not in the future). Without them, priority is 1.0 for the homepage, 0.8, 0.6 or 0.5 by depth and 0.3 for legal pages; changefreq is weekly for the homepage and blog index, yearly for legal pages and monthly otherwise.
  • disallow_pathsarray of stringsOptional
    Paths crawlers should skip, one Disallow rule each: up to 100, each starting with / or * and up to 500 characters. The wildcards * and $ work as in Google's robots.txt. Without any, robots.txt allows everything.
    Max items
    100
    Example
    ["/wp-admin/"]
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/robots-sitemap \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://gladiacteur.com",
    "pages": [
      {
        "path": "/"
      }
    ]
  }'

Response

200OKBoth files, where to serve them, and the crawl checks.

Response bodyapplication/json
  • robots_txtstring
    The complete robots.txt: User-agent: *, one Disallow line per disallow_paths entry (or Allow: / without any), and the sitemap URL.
  • sitemap_xmlstring
    The complete XML sitemap (sitemaps.org 0.9): one <url> per unique page with <loc>, <lastmod> when sent, <changefreq> and <priority>.
  • robots_urlstring (uri)
    Where robots.txt must be served: the site's origin plus /robots.txt.
  • sitemap_urlstring (uri)
    Where to serve the sitemap, as robots.txt references it: the origin plus /sitemap.xml.
  • url_countinteger
    URLs in the sitemap, after removing duplicates.
  • checksarray of objects
    Crawl checks, in this order: crawlable_site, sitemap_vs_robots, render_resources, canonical_urls_only, indexable_pages_only, trailing_slash_consistency, url_hygiene, https, homepage_listed, duplicates, lastmod and priority_changefreq (informational: Google ignores both tags).
    checks items(3)SeoCheck
    • checkstring
      Machine-readable name of the check, such as title_width or sitemap_vs_robots.
    • passboolean
      true when the check passes.
    • notestring
      What was measured or found and, on a failure, what to do about it. Always in English.
  • instructionsarray of strings
    Three steps: where to upload each file, and how to submit the sitemap to Google Search Console.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/robots-sitemapIllustrative

Request body
{
  "site_url": "https://gladiacteur.com",
  "pages": [
    {
      "path": "/",
      "changefreq": "daily"
    },
    {
      "path": "/ia-en-entreprise/",
      "lastmod": "2026-10-20"
    },
    {
      "path": "/10-outils-ia-pour-automatiser-son-business/",
      "lastmod": "2026-09-14"
    },
    {
      "path": "/contact/"
    }
  ],
  "disallow_paths": [
    "/wp-admin/"
  ]
}
Response · 200 OK
{
  "robots_txt": "# robots.txt for https://gladiacteur.com - generated by Autoranko\nUser-agent: *\nDisallow: /wp-admin/\n\nSitemap: https://gladiacteur.com/sitemap.xml\n",
  "sitemap_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n  <url>\n    <loc>https://gladiacteur.com/</loc>\n    <changefreq>daily</changefreq>\n    <priority>1.0</priority>\n  </url>\n  <url>\n    <loc>https://gladiacteur.com/ia-en-entreprise/</loc>\n    <lastmod>2026-10-20</lastmod>\n    <changefreq>monthly</changefreq>\n    <priority>0.8</priority>\n  </url>\n  <url>\n    <loc>https://gladiacteur.com/10-outils-ia-pour-automatiser-son-business/</loc>\n    <lastmod>2026-09-14</lastmod>\n    <changefreq>monthly</changefreq>\n    <priority>0.8</priority>\n  </url>\n  <url>\n    <loc>https://gladiacteur.com/contact/</loc>\n    <changefreq>monthly</changefreq>\n    <priority>0.8</priority>\n  </url>\n</urlset>\n",
  "robots_url": "https://gladiacteur.com/robots.txt",
  "sitemap_url": "https://gladiacteur.com/sitemap.xml",
  "url_count": 4,
  "checks": [
    {
      "check": "sitemap_vs_robots",
      "pass": true,
      "note": "No sitemap URL is blocked by robots.txt."
    },
    {
      "check": "indexable_pages_only",
      "pass": true,
      "note": "No utility pages (login, cart, search, thank-you) are listed."
    },
    {
      "check": "lastmod",
      "pass": false,
      "note": "2 URL(s) have no lastmod. Send the date each page last changed meaningfully. Google trusts lastmod only when it's consistently accurate, so never stamp every page with today's date."
    },
    {
      "check": "priority_changefreq",
      "pass": true,
      "note": "Google ignores <priority> and <changefreq>. They are filled in (defaults from page depth) for other crawlers; an accurate URL list and lastmod are what count."
    }
  ],
  "instructions": [
    "Upload robots.txt to the web root so it is served at https://gladiacteur.com/robots.txt. It only works at the root of the host.",
    "Upload sitemap.xml to the web root so it is served at https://gladiacteur.com/sitemap.xml with an XML content type.",
    "In Google Search Console (and Bing Webmaster Tools), open Sitemaps and submit sitemap.xml. Regenerate it whenever you add, remove or redirect pages."
  ],
  "analysis_id": "139"
}

Computed by the endpoint's own code; only analysis_id is illustrative. checks is shortened to 4 of 12.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodysite_url or pages is missing (site_url is required. or pages is required: a list of {path, priority?, changefreq?, lastmod?} (1-500 items).).
400invalid_bodyA path in pages is on another host (pages[1].path must be a path such as "/about", or a URL on gladiacteur.com: a sitemap can only list its own host's URLs.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (pages[0].lastmod must be a date (YYYY-MM-DD) or an ISO 8601 datetime.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

Preview a Google result

POSThttps://autoranko.com/api/public/v1/seo/serp-preview

Shows how a title, meta description and URL render on Google's results page. Widths are measured in pixels with Arial's metrics, the way Google truncates: about 580px for a desktop title, 920px for a description (two lines) and 680px for a description on mobile. preview holds the text exactly as searchers would see it, cut where Google would cut it, and the breadcrumb URL line.

checks passes or fails ten rules: lengths and widths, keyword placement (exact when you send keyword), a readable HTTPS URL, casing, keyword stuffing, and whether the description adds to the title. Nothing is fetched: it works on drafts too.

Pure computation: no AI call and nothing counted against the AI-call allowance, so only the rate limit applies.

Request

Body parametersapplication/json
  • titlestringRequired
    The title tag to preview.
    Max length
    300 characters
    Example
    Gladiacteur - IA, Technologie et Business : Outils & Tendances
  • descriptionstringRequired
    The meta description to preview.
    Max length
    1000 characters
    Example
    Découvrez comment l'IA et l'automatisation transforment les entreprises: outils, tendances et stratégies concrètes.
  • urlstring (uri)Required
    The page's URL, for the breadcrumb line and the URL checks: a public http or https URL (a bare host gets https://). It isn't fetched.
    Max length
    2048 characters
    Example
    https://gladiacteur.com/
  • keywordstringOptional
    The query the page targets. With it, keyword_placement checks that it's early in the title and in the description's first 120 characters; without it, the check only compares the title's lead words with the description.
    Max length
    120 characters
    Example
    IA business
  • savebooleanOptional
    Save the result to the account's SEO Lab history, shown in Dashboard → SEO Lab and listed by GET /seo/analyses. Send false to keep nothing; analysis_id is then null. Must be a JSON boolean.
    Default
    true
    Example
    true
curl -X POST https://autoranko.com/api/public/v1/seo/serp-preview \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Gladiacteur - IA, Technologie et Business : Outils & Tendances",
    "description": "Découvrez comment l'\''IA et l'\''automatisation transforment les entreprises: outils, tendances et stratégies concrètes.",
    "url": "https://gladiacteur.com/",
    "keyword": "IA business"
  }'

Response

200OKThe rendered preview, the measurements and the checks.

Response bodyapplication/json
  • previewobject
    The result as searchers would see it on desktop.
    preview keys(3)
    • title_shownstring
      The title as displayed: cut at a word boundary, with ... added, when it's wider than about 580px.
    • description_shownstring
      The description as displayed, cut the same way after about 920px (two lines).
    • breadcrumbstring
      The URL line under the site name: the host, then up to 3 path segments, separated by › .
  • measurementsobject
    Lengths and rendered widths. Widths are approximate pixels, computed from Arial's font metrics.
    measurements keys(3)
    • titleobject
      The title, at the size of a desktop result title.
      title keys(5)
      • charsinteger
        Length in characters.
      • pixelsinteger
        Rendered width in pixels.
      • limit_pixelsinteger
        Google's desktop limit for titles: 580.
      • truncatedboolean
        true when Google would cut it.
      • fontstring
        The font the widths assume: 20px Arial (approx.).
    • descriptionobject
      The meta description, at the size of a result snippet.
      description keys(7)
      • charsinteger
        Length in characters.
      • pixelsinteger
        Rendered width in pixels, on one line.
      • limit_pixelsinteger
        Google's desktop limit, two lines: 920.
      • mobile_limit_pixelsinteger
        Google's mobile limit: 680.
      • truncatedboolean
        true when Google would cut it on desktop.
      • fits_mobileboolean
        true when it fits on mobile too.
      • fontstring
        The font the widths assume: 14px Arial (approx.).
    • urlobject
      The URL.
      url keys(3)
      • charsinteger
        Length in characters.
      • path_depthinteger or null
        Number of path segments (/blog/post/ is 2), or null if the URL can't be parsed.
      • httpsboolean or null
        true for an HTTPS URL, or null if the URL can't be parsed.
  • checksarray of objects
    Ten pass/fail checks, in this order: title_length, title_width, description_length, description_width, keyword_placement, url_readable, https, title_case (not mostly uppercase), title_repetition (no keyword stuffing) and title_vs_description (the description adds to the title). keyword_placement is exact when a keyword is given; otherwise it's informational, comparing the title's lead words with the description.
    checks items(3)SeoCheck
    • checkstring
      Machine-readable name of the check, such as title_width or sitemap_vs_robots.
    • passboolean
      true when the check passes.
    • notestring
      What was measured or found and, on a failure, what to do about it. Always in English.
  • analysis_idstring or null
    ID of the result saved to the account's SEO Lab history (a 64-bit integer serialized as a string); fetch it again with GET /seo/analyses/{id}. null when save was false, or in the rare case the save failed: the result is returned either way.

Examples

POST/seo/serp-previewIllustrative

Request body
{
  "title": "Gladiacteur - IA, Technologie et Business : Outils & Tendances",
  "description": "Découvrez comment l'IA et l'automatisation transforment les entreprises: outils, tendances et stratégies concrètes.",
  "url": "https://gladiacteur.com/",
  "keyword": "IA business"
}
Response · 200 OK
{
  "preview": {
    "title_shown": "Gladiacteur - IA, Technologie et Business : Outils & Tendances",
    "description_shown": "Découvrez comment l'IA et l'automatisation transforment les entreprises: outils, tendances et stratégies concrètes.",
    "breadcrumb": "gladiacteur.com"
  },
  "measurements": {
    "title": {
      "chars": 62,
      "pixels": 559,
      "limit_pixels": 580,
      "truncated": false,
      "font": "20px Arial (approx.)"
    },
    "description": {
      "chars": 115,
      "pixels": 706,
      "limit_pixels": 920,
      "mobile_limit_pixels": 680,
      "truncated": false,
      "fits_mobile": false,
      "font": "14px Arial (approx.)"
    },
    "url": {
      "chars": 24,
      "path_depth": 0,
      "https": true
    }
  },
  "checks": [
    {
      "check": "title_length",
      "pass": true,
      "note": "62 characters, over the usual 60, but narrow enough to fit (559px). Google cuts by pixel width, not characters."
    },
    {
      "check": "title_width",
      "pass": true,
      "note": "About 559px of ~580px, so it shows in full on desktop."
    },
    {
      "check": "description_width",
      "pass": true,
      "note": "About 706px: fits two desktop lines (~920px). On mobile (~680px) it will be cut, so put the key promise first."
    },
    {
      "check": "keyword_placement",
      "pass": false,
      "note": "\"IA business\" is front-loaded in the title (with all its terms). Add it to the first 120 characters of the description: Google bolds matching query words, and mobile cuts the rest."
    },
    {
      "check": "title_vs_description",
      "pass": true,
      "note": "The description adds information beyond the title."
    }
  ],
  "analysis_id": "140"
}

Computed by the endpoint's own code; only analysis_id is illustrative. checks is shortened to 5 of 10.

Errors

ErrorWhen
400invalid_bodyThe body isn't a JSON object (Invalid JSON body. or The JSON body must be an object.).
400invalid_bodyThe body has a field the endpoint doesn't accept (Unknown field "…"). Names are exact, and a near miss such as targetKeyword gets a hint to the right one.
400invalid_bodytitle, description or url is missing (title is required.).
400invalid_bodyA field has the wrong type or is out of bounds (length, range, item count or format); message names it (description is too long (max 1000 characters).).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
413invalid_bodyThe body is larger than 2 MB (Request body too large (max 2 MB).).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

List saved analyses

GEThttps://autoranko.com/api/public/v1/seo/analyses

Lists the account's saved toolkit results, its SEO Lab history, newest first. Each entry is a summary without the request or the result: fetch one with GET /seo/analyses/{id}. Dashboard → SEO Lab shows the same history.

Filter by endpoint with kind. Page through the list with limit and offset until a page returns fewer than limit items; there's no total count.

Only saved results are listed: a call made with save: false leaves nothing here.

Request

Query parameters
  • kindstringOptional
    Only return results from this endpoint. An unknown value is rejected with 400 invalid_body.

    One ofanalyzekeywordsarticlearticle_shortmeta_tagsopen_graphschemaheadingscontent_briefrewritealt_textsrobots_sitemapserp_preview

    Example
    analyze
  • limitintegerOptional
    Page size. Values outside 1–100 are clamped to that range, not rejected.
    Default
    50
    Range
    1–100
    Example
    20
  • offsetintegerOptional
    How many results to skip, for pagination. Out-of-range values are clamped.
    Default
    0
    Range
    0–1000000
    Example
    0
curl "https://autoranko.com/api/public/v1/seo/analyses?kind=analyze&limit=20" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKOne page of saved results, newest first.

Response bodyapplication/json
  • analysesarray of objects
    Saved results, newest first.
    analyses items(4)SeoAnalysisSummary
    • idstring
      Analysis ID: a 64-bit integer serialized as a string. It's the analysis_id the endpoint returned.
    • kindstring
      The endpoint that produced the result: its last path segment with _ for -, such as article_short for POST /seo/article-short.

      One ofanalyzekeywordsarticlearticle_shortmeta_tagsopen_graphschemaheadingscontent_briefrewritealt_textsrobots_sitemapserp_preview

    • subjectstring
      What the request was about: the page URL, topic, keyword or site, depending on the endpoint (at most 500 characters).
    • created_atstring (date-time)
      When the result was saved.
  • limitinteger
    The page size that was applied (after clamping).
  • offsetinteger
    The offset that was applied (after clamping).

Examples

GET/seo/analyses?limit=3Illustrative

Response · 200 OK
{
  "analyses": [
    {
      "id": "141",
      "kind": "article",
      "subject": "Comment automatiser sa prospection B2B avec l'IA en 2026",
      "created_at": "2026-10-26T09:52:37.904Z"
    },
    {
      "id": "140",
      "kind": "serp_preview",
      "subject": "https://gladiacteur.com/",
      "created_at": "2026-10-26T09:49:12.118Z"
    },
    {
      "id": "139",
      "kind": "robots_sitemap",
      "subject": "https://gladiacteur.com",
      "created_at": "2026-10-26T09:49:10.551Z"
    }
  ],
  "limit": 3,
  "offset": 0
}

Errors

ErrorWhen
400invalid_bodykind isn't one of the analysis kinds (kind must be one of: …). The code is invalid_body even though kind is a query parameter.
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

Get a saved analysis

GEThttps://autoranko.com/api/public/v1/seo/analyses/{id}

Returns one saved toolkit result: the validated request that produced it and the full result, as the endpoint returned it (without analysis_id). id is the analysis_id from the toolkit response, or an id from GET /seo/analyses.

Requests and results are stored as JSON documents, so their keys can come back in a different order than in the original response.

Request

Path parameters
  • idintegerRequired
    Analysis ID: analysis_id from a toolkit response, or id from GET /seo/analyses.
curl https://autoranko.com/api/public/v1/seo/analyses/129 \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe saved result, with its request.

Response bodyapplication/json
  • analysisobject
    The saved result.
    analysis keys(6)SeoAnalysis
    • idstring
      Analysis ID: a 64-bit integer serialized as a string. It's the analysis_id the endpoint returned.
    • kindstring
      The endpoint that produced the result: its last path segment with _ for -, such as article_short for POST /seo/article-short.

      One ofanalyzekeywordsarticlearticle_shortmeta_tagsopen_graphschemaheadingscontent_briefrewritealt_textsrobots_sitemapserp_preview

    • subjectstring
      What the request was about: the page URL, topic, keyword or site, depending on the endpoint (at most 500 characters).
    • requestobject
      The request as validated, without save: values normalized (https:// added to a bare host, for example) and defaults filled in (mode, word_count, tone, …).
    • resultobject
      The response body the endpoint returned, without analysis_id.
    • created_atstring (date-time)
      When the result was saved.

Examples

GET/seo/analyses/129Illustrative

Response · 200 OK
{
  "analysis": {
    "id": "129",
    "kind": "keywords",
    "subject": "outils IA pour PME",
    "request": {
      "mode": "ideas",
      "topic": "outils IA pour PME",
      "country": "FR",
      "language": "fr"
    },
    "result": {
      "mode": "ideas",
      "keywords": [
        {
          "cpc": 2.4,
          "volume": 880,
          "keyword": "outils ia pour pme",
          "difficulty": 38,
          "competition": "MEDIUM",
          "competition_index": 54
        },
        {
          "cpc": 1.85,
          "volume": 590,
          "keyword": "meilleur outil ia gratuit entreprise",
          "difficulty": 35,
          "competition": "MEDIUM",
          "competition_index": 47
        }
      ],
      "estimated": true,
      "seeds_used": [
        "outils IA pour PME"
      ]
    },
    "created_at": "2026-10-26T09:41:58.372Z"
  }
}

The keywords example above as stored: keys inside request and result come back shortest first, and keywords is shortened.

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo saved analysis with this id belongs to your account (Analysis not found.).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

API version v1. Every path on this page is relative to https://autoranko.com/api/public/v1.