Skip to content

API quickstart

The API uses JSON over HTTPS. The full reference is generated from the OpenAPI description: API reference (file openapi.json in the reference).

1. Get a key

Create a project key (API keys) and keep it in an environment variable. Your base URL is the address of the app you were invited to.

export ASKANIELA_URL=https://<your-app-address>
export ASKANIELA_API_KEY=gsj_...

2. Check one page

curl -s "$ASKANIELA_URL/v1/judge" \
  -H "Authorization: Bearer $ASKANIELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/"}'

Send exactly one of url, html or text. Optional fields: rules (rule ids, see GET /v1/rules), render_js, explain (evidence for hits), query and market (search intent), project_id. The response lists violations (spam), quality_signals (quality), labels, positives and not_assessed, each with a rule_id and a risk score.

3. Search Intent for a phrase

curl -s "$ASKANIELA_URL/v1/intent" \
  -H "Authorization: Bearer $ASKANIELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best running shoes", "market": "en-US"}'

For many phrases use POST /v1/intent/batch or POST /v1/intent/batch/csv.

4. Larger work

  • POST /v1/judge/batch - up to 10 pages in one call.
  • POST /v1/jobs - asynchronous jobs, with optional webhooks (Webhooks and jobs).
  • POST /v1/audits/site/estimate then POST /v1/audits/site - site audits (Site audits).

5. Reports and usage

  • GET /v1/reports, GET /v1/reports/{id}, GET /v1/reports/{id}/export.pdf.
  • GET /v1/usage - your monthly limit and balance in USD.

When the limit is used up, the API returns 429 quota_exceeded. All error codes: Errors.