API tokens and REST API

Personal API tokens, scopes, and calling the REST API from scripts.

Personal API tokens

Create tokens in Settings → API & MCP. A token acts as you, with your current role, in one organization only: the one selected when it was created.

Property	Details
Format	`seo_pat_` followed by a random secret. Only a hash is stored; the token is shown once.
Access	Read + start jobs (any request) or Read only (GET requests only).
Expiry	30 days, 90 days (default), 1 year, or never. Up to 25 active tokens per person per organization.
Revocation	Revoke any time. Tokens also stop working when your account is suspended or you leave the organization.

Tokens can't create or revoke tokens, accept invitations, or reach the platform admin console. Those need a signed-in browser session.

Calling the API

Send the token as a bearer token. The organization comes from the token, so you don't need an organization header.

terminal

curl -H "Authorization: Bearer seo_pat_…" https://ai-seo.vdev.web.id/api/sites

audit from a script

TOKEN=seo_pat_…
API=https://ai-seo.vdev.web.id/api

# start an audit
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{}' $API/sites/$SITE_ID/audits

# poll until status is completed or failed
curl -H "Authorization: Bearer $TOKEN" $API/audits/$AUDIT_ID

# download the results
curl -H "Authorization: Bearer $TOKEN" $API/audits/$AUDIT_ID/export.json

Useful endpoints

Endpoint	Purpose
`GET /api/sites`	Your sites
`POST /api/sites/{id}/audits`	Start an audit (optional `crawl_config` overrides)
`GET /api/audits/{id}`	Status, stage, progress and score
`GET /api/audits/{id}/score`	Score and subscores
`GET /api/audits/{id}/findings`	Findings, filter by `check_id` or `severity`
`GET /api/audits/{id}/export.json`	The whole audit
`GET /api/audits/{id}/export.csv?part=issues`	Issues (or `part=recommendations`) as CSV
`GET /api/sites/{id}/issues`	Tracked issues, filter by `status`, `severity`, `check_id`
`GET /api/sites/{id}/recommendations`	Recommendations, filter by `status`, `priority`
`GET /api/sites/{id}/report?days=28`	Period summary

Status	Meaning
401	No valid token
403	Read-only token on a write, or not allowed with a token
404	Not found, including anything in another organization
409	Conflict, e.g. an audit is already running
422	Invalid input