API Reference

Programmatically run website audits and integrate results into your workflow

Quick Start

Send a POST request with your API key and target URL. You'll get a score, grade, and key SEO metrics back in under 15 seconds.

cURL

curl -X POST https://www.webenture.com/api/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Authentication

All API requests must include a Bearer token in the Authorization header. API keys are prefixed with wb_live_.

Authorization header format

Authorization: Bearer wb_live_your_api_key_here

Generate your API key

Create and manage keys from your dashboard.

Go to API Keys

Plan requirement

API access requires an Agency plan. Keys are scoped per-user with read/write permissions.

View pricing

Endpoints

2 endpoints

POST/api/v1/analyze

Analyzes a public URL and returns a score (0–100), load time, SEO signals, and content metrics. The request follows up to 5 redirects automatically.

Burst limit

30 req / IP

Per-key limit

100 req / hour

Timeout

15 s fetch

Max body

2 MB HTML

Request body (JSON)

Field	Type	Required	Description
url	string	yes	Full URL including scheme (https://...). Must be publicly reachable.

Example response — 200 OK

{
  "url": "https://example.com",
  "score": 87,
  "status": 200,
  "loadTimeMs": 1240,
  "title": "Example Domain",
  "metaDescription": null,
  "seo": {
    "hasMetaDescription": false,
    "hasOgTags": false,
    "isHttps": true,
    "h1Count": 1,
    "titleLength": 14
  },
  "content": {
    "totalImages": 0,
    "imagesWithoutAlt": 0,
    "totalLinks": 2
  },
  "analyzedAt": "2026-07-20T10:00:00.000Z"
}

Response fields

Field	Type	Description
url	string	The analyzed URL (after redirect resolution)
score	number	Overall score 0–100. Factors: HTTPS, title length, meta description, OG tags, load time
status	number	HTTP status code returned by the target URL
loadTimeMs	number	Time in milliseconds from request to first byte
title	string	Page <title> content
metaDescription	string \| null	Content of the meta description tag, or null if absent
seo.hasMetaDescription	boolean	Whether a meta description tag exists
seo.hasOgTags	boolean	Whether any og: meta property tags exist
seo.isHttps	boolean	Whether the final URL uses HTTPS
seo.h1Count	number	Number of <h1> tags on the page
seo.titleLength	number	Character count of the page title
content.totalImages	number	Total <img> tag count
content.imagesWithoutAlt	number	Images missing a non-empty alt attribute
content.totalLinks	number	Total <a> tag count (internal + external)
analyzedAt	string	ISO 8601 timestamp of when the analysis ran

POST/api/v1/audit

Runs one or more full agent analyzers (technical SEO, security, accessibility) against a public URL and returns per-agent scores, grades, and detailed findings. Built for CI/CD gates — call it after a deploy and fail the build on a score drop.

Request body (JSON)

Field	Type	Required	Description
url	string	yes	Full URL including scheme. Must be publicly reachable.
agents	string[]	no	Up to 3 of: `technical-seo`, `security`, `accessibility`. Defaults to all 3.

cURL

curl -X POST https://www.webenture.com/api/v1/audit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "agents": ["technical-seo", "security", "accessibility"]}'

Example response — 200 OK

{
  "url": "https://example.com",
  "timestamp": "2026-07-21T10:00:00.000Z",
  "agentsRun": [
    "technical-seo",
    "security",
    "accessibility"
  ],
  "scores": {
    "technical-seo": {
      "score": 84,
      "grade": "B",
      "issueCount": 6
    },
    "security": {
      "score": 91,
      "grade": "A",
      "issueCount": 2
    },
    "accessibility": {
      "score": 78,
      "grade": "C",
      "issueCount": 9
    }
  }
}

Each agent also returns a details object with the full finding list — omitted above for brevity.

CI/CD Integration

GitHub · GitLab · Vercel

Gate deploys on a score threshold. Each example calls /api/v1/audit after a deploy and fails the job when the score drops below your bar — swap the threshold and agent to match what you care about.

GitHub Actions — .github/workflows/webenture-audit.yml

name: WebEnture Audit
on: [deployment_status]

jobs:
  audit:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Run audit and fail below threshold
        env:
          WEBENTURE_API_KEY: ${{ secrets.WEBENTURE_API_KEY }}
        run: |
          SCORE=$(curl -s -X POST https://www.webenture.com/api/v1/audit \
            -H "Authorization: Bearer $WEBENTURE_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"url": "${{ github.event.deployment_status.target_url }}", "agents": ["technical-seo"]}' \
            | jq '.scores["technical-seo"].score')
          echo "Technical SEO score: $SCORE"
          if [ "$SCORE" -lt 70 ]; then
            echo "::error::Score $SCORE fell below threshold 70"
            exit 1
          fi

GitLab CI — .gitlab-ci.yml

webenture_audit:
  stage: test
  script:
    - >
      SCORE=$(curl -s -X POST https://www.webenture.com/api/v1/audit
      -H "Authorization: Bearer $WEBENTURE_API_KEY"
      -H "Content-Type: application/json"
      -d "{\"url\": \"$CI_ENVIRONMENT_URL\", \"agents\": [\"security\"]}"
      | jq '.scores.security.score')
    - echo "Security score $SCORE"
    - test "$SCORE" -ge 70

Vercel deploy hook / post-deploy script

# In a post-deploy step (e.g. a Vercel deploy hook consumer,
# or "vercel-build-output" webhook receiver):
curl -s -X POST https://www.webenture.com/api/v1/audit \
  -H "Authorization: Bearer $WEBENTURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$VERCEL_DEPLOYMENT_URL\"}"

Error Codes

// All errors return { error: string }

Status	Meaning
400	Invalid URL or missing parameters
401	Invalid or missing API key
403	API key lacks required permission
429	Rate limit exceeded — retry after the Retry-After header value
500	Internal server error
502	Target URL unreachable or returned no response

Rate-limited responses include a Retry-After header with seconds until reset.

SDKs & Libraries

Official SDKs are coming soon. In the meantime, use any HTTP client — the API is a single REST endpoint.

JavaScript (fetch)

const response = await fetch(
  "https://www.webenture.com/api/v1/analyze",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://example.com" }),
  }
);
const data = await response.json();
console.log(data.score); // 87

Python (requests)

import requests

response = requests.post(
    "https://www.webenture.com/api/v1/analyze",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"url": "https://example.com"},
)
data = response.json()
print(data["score"])  # 87

Try It

live

Make a live request from your browser

URL to analyze

API Key

Field

Type

Required

Description

url

string

yes

Full URL including scheme (https://...). Must be publicly reachable.

{ "url": "https://example.com", "score": 87, "status": 200, "loadTimeMs": 1240, "title": "Example Domain", "metaDescription": null, "seo": { "hasMetaDescription": false, "hasOgTags": false, "isHttps": true, "h1Count": 1, "titleLength": 14 }, "content": { "totalImages": 0, "imagesWithoutAlt": 0, "totalLinks": 2 }, "analyzedAt": "2026-07-20T10:00:00.000Z" }

Field

Type

Description

url

string

The analyzed URL (after redirect resolution)

score

number

Overall score 0–100. Factors: HTTPS, title length, meta description, OG tags, load time

status

number

HTTP status code returned by the target URL

loadTimeMs

number

Time in milliseconds from request to first byte

title

string

Page <title> content

metaDescription

string | null

Content of the meta description tag, or null if absent

seo.hasMetaDescription

boolean

Whether a meta description tag exists

seo.hasOgTags

boolean

Whether any og: meta property tags exist

seo.isHttps

boolean

Whether the final URL uses HTTPS

seo.h1Count

number

Number of <h1> tags on the page

seo.titleLength

number

Character count of the page title

content.totalImages

number

Total <img> tag count

content.imagesWithoutAlt

number

Images missing a non-empty alt attribute

content.totalLinks

number

Total <a> tag count (internal + external)

analyzedAt

string

ISO 8601 timestamp of when the analysis ran

Field

Type

Required

Description

url

string

yes

Full URL including scheme. Must be publicly reachable.

agents

string[]

Up to 3 of: technical-seo, security, accessibility. Defaults to all 3.

curl -X POST https://www.webenture.com/api/v1/audit \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com", "agents": ["technical-seo", "security", "accessibility"]}'

{ "url": "https://example.com", "timestamp": "2026-07-21T10:00:00.000Z", "agentsRun": [ "technical-seo", "security", "accessibility" ], "scores": { "technical-seo": { "score": 84, "grade": "B", "issueCount": 6 }, "security": { "score": 91, "grade": "A", "issueCount": 2 }, "accessibility": { "score": 78, "grade": "C", "issueCount": 9 } } }

name: WebEnture Audit on: [deployment_status] jobs: audit: if: github.event.deployment_status.state == 'success' runs-on: ubuntu-latest steps: - name: Run audit and fail below threshold env: WEBENTURE_API_KEY: ${{ secrets.WEBENTURE_API_KEY }} run: | SCORE=$(curl -s -X POST https://www.webenture.com/api/v1/audit \ -H "Authorization: Bearer $WEBENTURE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "${{ github.event.deployment_status.target_url }}", "agents": ["technical-seo"]}' \ | jq '.scores["technical-seo"].score') echo "Technical SEO score: $SCORE" if [ "$SCORE" -lt 70 ]; then echo "::error::Score $SCORE fell below threshold 70" exit 1 fi

webenture_audit: stage: test script: - > SCORE=$(curl -s -X POST https://www.webenture.com/api/v1/audit -H "Authorization: Bearer $WEBENTURE_API_KEY" -H "Content-Type: application/json" -d "{\"url\": \"$CI_ENVIRONMENT_URL\", \"agents\": [\"security\"]}" | jq '.scores.security.score') - echo "Security score $SCORE" - test "$SCORE" -ge 70

# In a post-deploy step (e.g. a Vercel deploy hook consumer, # or "vercel-build-output" webhook receiver): curl -s -X POST https://www.webenture.com/api/v1/audit \ -H "Authorization: Bearer $WEBENTURE_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"url\": \"$VERCEL_DEPLOYMENT_URL\"}"

Status

Meaning

400

Invalid URL or missing parameters

401

Invalid or missing API key

403

API key lacks required permission

429

Rate limit exceeded — retry after the Retry-After header value

500

Internal server error

502

Target URL unreachable or returned no response

const response = await fetch( "https://www.webenture.com/api/v1/analyze", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://example.com" }), } ); const data = await response.json(); console.log(data.score); // 87

import requests response = requests.post( "https://www.webenture.com/api/v1/analyze", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, json={"url": "https://example.com"}, ) data = response.json() print(data["score"]) # 87