Skip to content
SEOComet

Article check API

Check articles from your CMS or scripts: API keys, the three endpoints, curl examples, signed callbacks and the limits.

Updated

The article check API lets your own tools check an article the way Check an article does in the app: your CMS before you publish, a script that checks every new post, or anything else that can send an HTTPS request.

It has three endpoints: list your sites, start a check, and read a check back. A check can also post its result to your server when it finishes.

API keys

You make keys in Account › API keys. The owner and people who can edit all sites can make and revoke them. People who can only view, or who have selected sites, don’t see the page.

  1. Choose Make a key and name it after where you’ll use it, such as “WordPress” or “Newsroom CMS”.
  2. Copy the key. It starts with sc_live_ and is shown once: SEOComet only keeps a fingerprint of it.

A key belongs to the account, not to the person who made it: it works on every site in the account. Keep it on a server, not in a browser or an app other people can open. The API sends no CORS headers, so a web page on another domain can’t call it.

If a key leaks, or a tool doesn’t need it any more, choose Revoke next to it. It stops working at once. The list shows when each key was made, by whom, and when it was last used. An account can have 25 keys in use.

Keys made by someone who leaves the account, is removed, or no longer has Can edit on every site are revoked automatically, and the activity log says how many. Make the keys your tools rely on from an owner’s login, or make new ones when someone leaves.

Sending requests

Every address starts with https://www.seocomet.com/api/v1. Send the key in the Authorization header as a Bearer token. A request with a body sends a JSON object with Content-Type: application/json, and every answer is JSON.

Errors come with a message:

  • 400: the body isn’t JSON. “The request body isn’t valid JSON.” means it didn’t parse. “Send JSON with Content-Type: application/json.” means the header is missing or says something else, which is also what a form post gets.
  • 401: the key is missing, wrong or revoked. The message says which. After 20 wrong or revoked keys in a minute from one address, wrong and revoked keys from that address get a 429 until the minute is up. A valid key keeps working.
  • 404: the site or check isn’t in the key’s account, or there’s no such address.
  • 405: the address exists but not with that method. The Allow header lists the ones it takes.
  • 422: a field isn’t valid. errors lists the problems by field, each a sentence that names the field and the rule. Read errors rather than message, which only carries the first one.
  • 429: a limit was reached. See Limits.
  • 500: something went wrong on our side. The body is {"message": "Server Error"}. Try again in a moment.
{
  "message": "headline is required when source is paste. (and 1 more error)",
  "errors": {
    "headline": ["headline is required when source is paste."],
    "body": ["body is required when source is paste."]
  }
}

Listing your sites

GET /sites lists every site in the account by name. You need a site’s id to check an article on it.

curl https://www.seocomet.com/api/v1/sites \
  -H "Authorization: Bearer $SEOCOMET_API_KEY"
{
  "data": [
    { "id": 3, "name": "Acme Store", "url": "https://acme.test" }
  ]
}

Checking an article

POST /sites/{site}/article-checks starts a check and answers 202 with the new check. It runs in the background, usually in a few seconds, so its status is queued or running in that answer more often than not. A quick check can already be done or failed, so read the status rather than assume one.

Check a draft by pasting it:

  • source: paste.
  • headline: the headline, up to 300 characters.
  • body: the article, as plain text or HTML, up to 200,000 characters, and 50 words or more: a shorter draft isn’t scored and the check fails with too_short.
  • meta_description (optional): up to 500 characters. A longer one is cut to that length and the check still runs.
  • preview_url (optional): the draft’s preview link, on the site’s own address. SEOComet reads it to check the template: structured data, the canonical tag, images and the rest. It must open without signing in.

Or check a published page:

  • source: url.
  • url: the page’s full address, on the site’s own address.

Either way you can add:

  • primary_keyword (optional): the search the article should rank for, up to 100 characters. A longer one is left out and the check runs without a keyword. Three of the 100 points are for where your keyword sits in the title. Without a keyword they’re left out, so a full check is scored out of 97 (score.checked). The AI check suggests a keyword in result.ai.focus.primary_keyword; it’s shown for reference and never scored.
  • ai (optional): true or false, whether to include the AI check. It’s on unless you send false, so every check you start spends the plan’s monthly AI credits: as many as the account’s AI model costs, 1 on Standard and 10 on Deeper. The model is chosen under Account › Details. Send false when the rule-based score is enough. Without enough credits left the check still runs, and result.ai.status says the AI part was left out. Text such as "no" or "false" is refused with a 422.
  • callback_url (optional): an https:// address on the public internet to post the result to when the check finishes. See Callbacks.
curl https://www.seocomet.com/api/v1/sites/3/article-checks \
  -H "Authorization: Bearer $SEOCOMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "paste",
    "headline": "How to choose a CRM for a small sales team",
    "body": "Pick the CRM your reps will update every day. For a sales team of 2 to 20 people, that means a simple pipeline view, a mobile app and email sync. Start with three stages and add more later. Track the deal value and the next step for every deal, and nothing else for the first month. Review the pipeline together every Monday.",
    "primary_keyword": "crm for small sales team",
    "preview_url": "https://acme.test/?p=4812&preview=true"
  }'

The answer has the check under data, in the shape Reading a check describes, and a warnings list:

{
  "data": { "id": 812, "site_id": 3, "status": "queued", … },
  "warnings": []
}

warnings is empty unless SEOComet changed something to let the check run: a meta_description it cut, or a primary_keyword it left out. Each entry names the field and says what happened in a message. It’s only in this answer, not in the check you read back later.

"warnings": [
  {
    "field": "meta_description",
    "message": "meta_description was longer than 500 characters, so only the first 500 were checked."
  }
]

Which addresses a check can read

url and preview_url must be on the site you’re checking: the host GET /sites shows for it, or a subdomain of it, with or without www. The scheme and the port must be the site’s too, so a site on https://acme.test doesn’t take http://acme.test/… or https://acme.test:8443/…. An address on another host gets a 422 that names the host the site has. To check pages there, add that site in SEOComet first and use its id. Private and reserved addresses, such as 127.0.0.1 or 10.0.0.8, are always refused.

Reading a check

GET /article-checks/{id} returns the check:

curl https://www.seocomet.com/api/v1/article-checks/812 \
  -H "Authorization: Bearer $SEOCOMET_API_KEY"
{
  "data": {
    "id": 812,
    "site_id": 3,
    "status": "done",
    "failure_reason": null,
    "failure_code": null,
    "headline": "How to choose a CRM for a small sales team",
    "url": null,
    "score": { "earned": 68, "checked": 100, "possible": 100, "band": "needs_work" },
    "result": { "version": 2, "score": { … }, "parts": [ … ], "fixes": [ … ], "ai": { … } },
    "app_url": "https://www.seocomet.com/sites/3/article-check/812",
    "created_at": "2026-10-24T10:00:00+00:00"
  }
}
  • status: queued, running, done or failed.
  • failure_reason: why it failed, a sentence you can show, such as “The preview link asks for a sign-in”. Null unless it failed.
  • failure_code: which failure it was, for your code to act on. unreadable_article: the address opened, but what is on it isn’t an article SEOComet can read (a subscribers-only page, a product or category page, a page built in the browser, a page with under 50 words of article text). sign_in: the address opens a sign-in page. preview_sign_in: the preview link asks for a sign-in. too_short: a pasted draft under 50 words. fetch_failed: the address couldn’t be fetched or answered an error. not_html: it isn’t an HTML page. other_host: it redirected to another site. didnt_finish and internal_error: the check stopped on our side, so start it again. If its AI call had already gone out, the check keeps those AI credits and failure_reason says so. Null unless it failed. Treat a code you don’t know as a failure and show failure_reason.
  • score: the points earned out of the points that could be checked, and what a full check is worth (possible). checked is 100 for a full check with a primary keyword and 97 without one, and 3 less again when the page doesn’t say how wide its lead image is and the image couldn’t be read. band is strong (90 and up), good (80 to 89) or needs_work (under 80), worked out from earned out of checked, and null when the AI parts weren’t scored. The same article checked twice can differ by a few points, because the AI parts are a model’s judgement, so show the band beside the number. Null until it’s done.
  • result: everything the result page shows: each part’s score and findings, the fixes in order, the search preview, the checklist, and the AI check. Fixes come the most serious first, then by points. One with scored set to false adds no points: it’s worth doing, such as shortening a title that results would cut off. Null until it’s done.
  • app_url: the result page in SEOComet, for a “View in SEOComet” link. It needs a SEOComet login.

result.ai.status says what happened to the AI check:

  • done: it ran, and its parts are in the score.
  • not_requested: the check was started with ai set to false.
  • over_limit: the plan’s AI credits for this month don’t cover it.
  • not_configured: the AI check isn’t available on SEOComet at the moment.
  • failed: the AI check didn’t answer, or gave an answer SEOComet couldn’t use. A call that reached the AI model uses its credits whether or not the answer could be used, because the model may bill for it. Only a call that never went out, or that the model turned down with an error, uses none.

In every case but done the score covers the rule-based parts only. For over_limit, not_configured and failed, result.ai.message is a sentence you can show.

Without a callback, read the check every few seconds until it’s done or failed. Reading a check has its own limit, so polling doesn’t use up the requests the rest of the API gets (see Limits). A check that hasn’t finished after 10 minutes reads as failed, and sends no callback, so read a check you’ve heard nothing about by then.

Callbacks

Start a check with a callback_url and SEOComet posts to it once the check is done or failed:

curl https://www.seocomet.com/api/v1/sites/3/article-checks \
  -H "Authorization: Bearer $SEOCOMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "url",
    "url": "https://acme.test/blog/choose-a-crm",
    "callback_url": "https://cms.example.com/seocomet-callback"
  }'

The address must start with https://, carry no username or password, and be at most 2,048 characters. Its host isn’t looked up when you start the check. It’s looked up each time SEOComet posts, and a host that resolves to a private or reserved address gets nothing.

The body is JSON:

{
  "event": "article_check.completed",
  "data": { "id": 812, "status": "done", … }
}

data is the same as GET /article-checks/{id} returns. The SEOComet-Event header is article_check.completed, for a failed check as well as a finished one: look at data.status to tell them apart.

Answer with any 2xx. Any other answer is retried, and so is no answer: your server has 5 seconds to accept the connection and 10 seconds in all to answer. There are 3 tries in all, waiting 30 seconds and 2 minutes in between. A redirect (3xx) or a 410 ends it at once, since SEOComet doesn’t follow redirects when it posts. If every try fails, the result is still there to read.

Checking a callback

Each callback is signed with the account’s callback signing secret, on the API keys page under Reveal. The SEOComet-Signature header looks like t=1792836000,v1=5257a8…:

  • t: when it was signed, in Unix seconds. Refuse anything more than 300 seconds off your clock, so an old callback can’t be replayed.
  • v1: the hex HMAC-SHA256 of t, a full stop and the raw body, keyed with the secret.

Compare the signature over the raw body as it arrived. Parsing the JSON and turning it back into text can change it.

// Node.js, with the raw request body as a string
const crypto = require('crypto');

function isFromSEOComet(rawBody, header, secret) {
  const parts = {};
  for (const part of (header || '').split(',')) {
    const [name, value] = part.split('=');
    parts[name] = value;
  }
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || !(age <= 300)) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  // timingSafeEqual throws unless both are the same number of bytes.
  const received = Buffer.from(parts.v1);
  const wanted = Buffer.from(expected);

  return received.length === wanted.length &&
    crypto.timingSafeEqual(received, wanted);
}

// isFromSEOComet(rawBody, req.headers['seocomet-signature'], process.env.SEOCOMET_WEBHOOK_SECRET)
<?php
// PHP, with the raw request body
function is_from_seocomet(string $rawBody, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $part) {
        [$name, $value] = array_pad(explode('=', $part, 2), 2, '');
        $parts[$name] = $value;
    }

    $timestamp = $parts['t'] ?? '';
    if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);

    return hash_equals($expected, $parts['v1'] ?? '');
}

is_from_seocomet(
    file_get_contents('php://input'),
    $_SERVER['HTTP_SEOCOMET_SIGNATURE'] ?? '',
    (string) getenv('SEOCOMET_WEBHOOK_SECRET'),
);

If the secret leaks, choose Make a new secret. The old one stops working at once, so update your server straight after.

Limits

Each key has three limits a minute, counted apart:

  • 10 checks started. Only a check that starts counts: a request refused with a 400, 404, 422 or 429 doesn’t.
  • 300 reads of a check (GET /article-checks/{id}), so several editors can poll on one key.
  • 60 other requests: listing sites and sending start requests, refused ones included.

Checks started through the API count toward the plan’s monthly article checks, the same as checks started in the app: Free 20, Pro 500 and Business 2,000. A check that fails doesn’t count: if SEOComet couldn’t fetch or read the page, or something went wrong on our side, the month’s allowance gets that check back. A mistyped address costs nothing.

Over a limit, the answer is a 429 with a message to show, the limit that was reached, and a reason:

  • rate_limit: too many requests, reads, checks or wrong keys this minute. The Retry-After header says how many seconds to wait. X-RateLimit-Limit and X-RateLimit-Remaining are on these answers too, and on every answer that counts toward the requests or the reads.
  • monthly_limit: the plan’s article checks for this month are used up. Retrying won’t help until the month turns over or the plan changes, and there’s no Retry-After.
{
  "message": "Free includes 20 article checks a month. Upgrade to Pro for up to 500 article checks a month.",
  "reason": "monthly_limit",
  "limit": 20
}