Site Audit

curl --request POST \
  --url https://api.example.com/seo/audit

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/seo/audit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/seo/audit"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/seo/audit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

seo

audit

Site Audit

curl --request POST \
  --url https://api.example.com/seo/audit

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/seo/audit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/seo/audit"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/seo/audit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Overview

The Site Audit endpoint lets you check how healthy a page is across:

Performance
Accessibility
Best practices
SEO

Each audit returns an overall score from 0–100, individual category scores, detailed on-page metrics, approximate performance timings, and an optional snapshot of the page hero.

Each audit uses 1 credit from your balance.

Endpoint

POST https://api.gistmag.co.uk/seo/audit
Content-Type: application/json

Request Body

{
  "api_key": "your_api_key_here",
  "url": "https://www.example.co.uk",
  "include_screenshot": true,
  "source": "web"
}

api_key (required) – Your GistMag API key. You can create and manage keys in the dashboard.
url (required) – The page URL to audit. Must be publicly accessible.
include_screenshot (optional, default: true) – Include a base64 snapshot of the hero/above-the-fold area.
source (optional, default: "web") – One of:
- web
- api
- extension
- wordpress
- shopify
- batch
- tts

If an invalid value is provided for source, it is normalised to web.

Example Request

curl -X POST https://api.gistmag.co.uk/seo/audit \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "url": "https://www.example.co.uk",
    "include_screenshot": true,
    "source": "web"
  }'

Response

{
  "audit_id": "0c3a2a4d-1234-4b9e-8f3b-abc123def456",
  "url": "https://www.example.co.uk/",
  "requested_url": "https://www.example.co.uk",
  "overall_score": 82,
  "categories": {
    "performance": {
      "score": 78,
      "issues": [
        "Slow page load time (~2300 ms)."
      ]
    },
    "accessibility": {
      "score": 90,
      "issues": [
        "1 images are missing alt text."
      ]
    },
    "best_practices": {
      "score": 80,
      "issues": [
        "No canonical URL found; consider adding a canonical tag."
      ]
    },
    "seo": {
      "score": 85,
      "issues": [
        "Missing meta description"
      ]
    }
  },
  "issues": [
    "[performance] Slow page load time (~2300 ms).",
    "[accessibility] 1 images are missing alt text.",
    "[best_practices] No canonical URL found; consider adding a canonical tag.",
    "[seo] Missing meta description"
  ],
  "metrics": {
    "title": {
      "value": "Example",
      "length": 7,
      "status": "ok"
    },
    "meta_description": {
      "value": "",
      "length": 0,
      "status": "missing"
    },
    "canonical": "https://www.example.co.uk/",
    "robots": "",
    "h1_count": 1,
    "h2_count": 3,
    "word_count": 950,
    "internal_links": 15,
    "external_links": 4,
    "broken_links": 0,
    "images_without_alt": 1,
    "indexable": true,
    "follow_links": true
  },
  "performance": {
    "load_time_ms": 2300,
    "dom_content_loaded_ms": 1800,
    "time_to_first_byte_ms": 420
  },
  "screenshot_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Fields

audit_id – Unique identifier for the audit.
url – Final URL after redirects.
requested_url – URL as originally requested.
overall_score – Average of the four category scores.
categories – Object containing category-level scores and issues:
- performance
- accessibility
- best_practices
- seo
issues – Flattened list of issues with category prefixes for quick scanning.
metrics – Structured on-page metrics (titles, descriptions, headings, links, word count, indexability, etc.).
performance – Approximate timings:
- load_time_ms
- dom_content_loaded_ms
- time_to_first_byte_ms
screenshot_base64 – Optional PNG screenshot of the hero/above-the-fold area, base64-encoded. Omitted when include_screenshot is false.

Errors

Common error responses include:

400 – Missing or invalid url.
401 – Invalid api_key.
402 – Not enough credits (returned from the credit system).
502 – Upstream fetch failed for the target URL.

Error bodies follow the standard error shape described in the API overview.

Overview

Alt Text Generation

Text-to-Speech

Blog Meta Generator

Site Audit

Indexing

Management

Site Audit

Overview

Endpoint

Request Body

Example Request

Response

Fields

Errors

​Overview

​Endpoint

​Request Body

​Example Request

​Response

​Fields

​Errors

Overview

Endpoint

Request Body

Example Request

Response

Fields

Errors