API Reference

OmniRank Public API

Integrate OmniRank into your workflow. Trigger audits, fetch rankings, and retrieve SEO scores programmatically via a simple REST API.

On this page

Authentication Base URL Errors Websites Audits Keywords

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from Dashboard → Settings → API Keys.

curl -H "Authorization: Bearer or_live_xxxxxxxxxxxxxxxx" \
  https://omnirank.net/api/v1/websites

Keep your API key secret. Never expose it in client-side code or public repositories.

Base URL

https://omnirank.net/api/v1

All endpoints below are relative to this base URL. Responses are JSON with UTF-8 encoding. All timestamps are ISO 8601 UTC.

Errors

Errors return a JSON body with an error field.

Status	Meaning
400	Bad Request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
402	Payment Required — audit credit limit reached
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded (60 req/min)
500	Internal Server Error — please retry after a moment

Websites

GET/websites Auth required

List all websites in your account.

Example Response

{
  "websites": [
    {
      "id": "wbs_01...",
      "url": "https://example.com",
      "name": "Example",
      "verified": true,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST/websites Auth required

Add a new website to your account.

Parameters

Name	Type	Required	Description
url	string	yes	The full URL of the website, e.g. https://example.com
name	string	no	Display name (auto-generated from URL if omitted)

Example Response

{
  "website": {
    "id": "wbs_01...",
    "url": "https://example.com",
    "name": "Example",
    "verified": false,
    "verification_token": "omnirank-verify-abc123"
  }
}

GET/websites/:id Auth required

Retrieve a single website by ID.

Parameters

Name	Type	Required	Description
id	string	yes	Website ID

DELETE/websites/:id Auth required

Delete a website and all associated data.

Parameters

Name	Type	Required	Description
id	string	yes	Website ID

Audits

POST/audits Auth required

Trigger a new full SEO audit for a verified website.

Parameters

Name	Type	Required	Description
website_id	string	yes	ID of the verified website to audit

Example Response

{
  "audit_id": "aud_01...",
  "status": "queued"
}

GET/audits/:id Auth required

Get the status and results of an audit.

Parameters

Name	Type	Required	Description
id	string	yes	Audit ID

Example Response

{
  "audit": {
    "id": "aud_01...",
    "status": "completed",
    "score_overall": 78,
    "score_technical": 82,
    "score_onpage": 74,
    "score_offpage": 65,
    "score_speed": 90,
    "pages_crawled": 42,
    "issues_critical": 3,
    "issues_warning": 11,
    "completed_at": "2025-01-01T00:05:30Z"
  }
}

GET/websites/:id/audits Auth required

List all audits for a website, newest first.

Parameters

Name	Type	Required	Description
id	string	yes	Website ID
limit	integer	no	Max results to return (default 20, max 100)
offset	integer	no	Pagination offset

Keywords

GET/websites/:id/keywords Auth required

Get current keyword rankings for a website.

Parameters

Name	Type	Required	Description
id	string	yes	Website ID

Example Response

{
  "keywords": [
    {
      "keyword": "best seo tool",
      "position": 4,
      "engine": "google",
      "url_ranked": "https://example.com/blog/seo",
      "checked_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Rate Limits

All API requests are rate-limited to 60 requests per minute per API key.

Audit credits are limited by your plan. Check your usage at Dashboard → Billing.

If you exceed the rate limit, you will receive a 429 response. Retry after the duration specified in the Retry-After header.

Need help with the API?

Contact our team — we typically respond within a few hours.

Contact support