Skip to content
User guide menu API and API keys Pages

API and API keys

Create API keys, start audits with the seoscore REST API, read the results, and understand abilities, rate limits and credit charges.

Plans
Pro and up
Updated
On this page
  1. Create a key
  2. Start an audit
  3. Read the result
  4. Errors and limits
  5. Revoke a key
  6. Other ways in

The seoscore API lets your own code start audits and read the results, for example from a deploy script or an internal dashboard. Calls use your team's credits, just like the app.

Create a key

  1. Open Settings › API keys.
  2. Give the key a Name, such as the server or tool that will use it, and set its Requests a minute.
  3. Under What it can do, tick Audits to run audits, or AI connector for AI agents you build. See AI assistants.
  4. Press Create key and copy it straight away. We only show it once.

Start an audit

Send the key as Authorization: Bearer <key> or X-Api-Key: <key>.

curl -X POST https://seoscore.app/api/audit \
  -H "Authorization: Bearer $SEOSCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"url": "https://example.com"}'

The answer is 202 Accepted with the audit's id, its status_url and a report_url for the full report in the app. If an audit of that site is already waiting or running, you get that one back with 200 OK, and nothing is charged.

Read the result

Poll the status_url with the same key every few seconds:

curl https://seoscore.app/api/audits/123 \
  -H "Authorization: Bearer $SEOSCORE_API_KEY" \
  -H "Accept: application/json"

While it runs, status is queued or running. When it's completed, the answer includes the score, the previous_score and change, each area's points under categories, and the biggest fixes under issues. A failed audit has the reason in error.

Errors and limits

StatusMeaning
401The key is missing, wrong, revoked or expired.
402Not enough credits, an action your plan doesn't include, or no room for another site on your plan.
403The key doesn't have the ability this call needs.
404The audit doesn't exist or isn't your team's.
422The request is invalid, such as a missing url. The answer says which field.
429Too many requests. Wait for the number of seconds in the Retry-After header.

Keys allow 60 requests a minute unless you set another number when you create them.

Revoke a key

On Settings › API keys, each key shows when it was last used. Revoke a key you no longer need, or think may have leaked. It stops working straight away.

Other ways in

  • To audit after every deploy without writing code, use GitHub Actions.
  • To have results pushed to you instead of polling, use Webhooks.

Try it on your own site. The Free plan needs no card.

Get my free score