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.
- In the app
- Settings › API keys
- Plans
- Pro and up
- Updated
On this page
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.
Pro API keys are on Pro and up
Team owners and admins can create and revoke keys.
Create a key
- Open Settings › API keys.
- Give the key a Name, such as the server or tool that will use it, and set its Requests a minute.
- Under What it can do, tick Audits to run audits, or AI connector for AI agents you build. See AI assistants.
- Press Create key and copy it straight away. We only show it once.
Keep keys secret
Anyone with a key can spend your team's credits. Store it in a secret manager or your CI's secrets, never in your code. Give each tool its own key, so you can revoke one without breaking the others.
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.
www., http or a trailing slash still finds the same site. A new website adds a new site, which has to fit your plan.
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
| Status | Meaning |
|---|---|
401 | The key is missing, wrong, revoked or expired. |
402 | Not enough credits, an action your plan doesn't include, or no room for another site on your plan. |
403 | The key doesn't have the ability this call needs. |
404 | The audit doesn't exist or isn't your team's. |
422 | The request is invalid, such as a missing url. The answer says which field. |
429 | Too 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.