GlobalDex
REST API v1

API Documentation

Integrate agent-readiness scanning into your apps, CI/CD pipelines, browser extensions, or monitoring dashboards.

Quick Start

No API key required for the free tier (10 requests/minute, 100/day per IP). For higher limits, include your API key in the header.

# Scan a URL
curl -X POST https://globaldex.ai/api/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# With API key (higher limits)
curl -X POST https://globaldex.ai/api/v1/scan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ar_your_key_here" \
  -d '{"url": "https://example.com"}'

Base URL

https://globaldex.ai/api/v1

Authentication

Pass your API key via the Authorization header or x-api-key header.

TierRate LimitDaily LimitAuth
Free10 req/min100 req/dayNone (IP-based)
Pro60 req/min5,000 req/dayAPI Key
Enterprise300 req/min100,000 req/dayAPI Key

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-LimitMax requests per minute
X-RateLimit-RemainingRequests remaining in window
X-RateLimit-ResetSeconds until window resets
X-RateLimit-TierYour current tier

Endpoints

POST/api/v1/scan

Run a Scan

Scan a URL and get a full agent-readiness report. Results are persisted and appear on the leaderboard.

Request Body

NameTypeRequiredDescription
urlstringrequiredFull URL to scan (https://example.com)

Example

curl -X POST https://globaldex.ai/api/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}'

Response

{
  "id": "a1b2c3d4-...",
  "url": "https://stripe.com",
  "domain": "stripe.com",
  "score": 80,
  "grade": "B",
  "has_webmcp": false,
  "checks_passed": 12,
  "checks_total": 20,
  "categories": [
    {
      "name": "structure",
      "label": "Structure",
      "score": 20,
      "max_score": 25,
      "percentage": 80,
      "checks": [...]
    }
  ],
  "scanned_at": "2026-02-18T..."
}
GET/api/v1/lookup?domain=stripe.com

Lookup a Domain

Retrieve the latest scan result for a domain without running a new scan. Add &history=true for all scans.

Query Parameters

NameTypeRequiredDescription
domainstringrequiredDomain to look up (e.g. stripe.com)
historybooleanoptionalSet to 'true' to return all scans

Example

curl https://globaldex.ai/api/v1/lookup?domain=stripe.com

Response

{
  "id": "a1b2c3d4-...",
  "domain": "stripe.com",
  "score": 80,
  "grade": "B",
  "has_webmcp": false,
  "checks_passed": 12,
  "checks_total": 20,
  "scanned_at": "2026-02-18T...",
  "results": { ... }
}
GET/api/v1/domains

List All Domains

Browse the full dataset of scanned domains with filtering and pagination.

Query Parameters

NameTypeRequiredDescription
limitnumberoptionalResults per page (default 50, max 500)
offsetnumberoptionalPagination offset (default 0)
sortstringoptional'score' | 'recent' | 'domain'
min_scorenumberoptionalFilter domains with score >= value
webmcpbooleanoptional'true' to show only WebMCP-enabled

Example

curl "https://globaldex.ai/api/v1/domains?sort=score&limit=10&min_score=80"

Response

{
  "domains": [
    {
      "domain": "basecamp.com",
      "score": 89,
      "grade": "B",
      "has_webmcp": false,
      "total_scans": 1,
      "first_seen": "2026-02-18T...",
      "last_seen": "2026-02-18T..."
    }
  ],
  "total": 500,
  "limit": 10,
  "offset": 0,
  "sort": "score"
}
GET/api/v1/stats

Global Statistics

Aggregated statistics across the entire dataset — score distributions, WebMCP adoption, category averages.

Query Parameters

NameTypeRequiredDescription

Example

curl https://globaldex.ai/api/v1/stats

Response

{
  "total_scans": 510,
  "total_domains": 500,
  "avg_score": 72.4,
  "median_score": 74,
  "max_score": 89,
  "min_score": 15,
  "webmcp_adoption": {
    "count": 0,
    "percentage": 0
  },
  "score_distribution": {
    "A": 12, "B": 145, "C": 198, "D": 102, "F": 43
  },
  "category_averages": [
    { "category": "structure", "avg_percentage": 78 },
    { "category": "metadata", "avg_percentage": 65 }
  ]
}
GET/api/v1/badge?domain=stripe.com

Embeddable Badge

Returns an SVG badge image you can embed in READMEs, docs, or websites. Shows the domain's score and grade.

Query Parameters

NameTypeRequiredDescription
domainstringrequiredDomain to show badge for
stylestringoptional'flat' (default) or 'for-the-badge'

Example

![GlobalDex](https://globaldex.ai/api/v1/badge?domain=stripe.com)

Response

<!-- Returns SVG image -->
<img src="https://globaldex.ai/api/v1/badge?domain=stripe.com" alt="GlobalDex Score" />

Integration Examples

JavaScript / TypeScript

const response = await fetch("https://globaldex.ai/api/v1/scan", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ar_your_key_here",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

const data = await response.json();
console.log(`Score: ${data.score}/100 (Grade: ${data.grade})`);

Python

import requests

response = requests.post(
    "https://globaldex.ai/api/v1/scan",
    json={"url": "https://example.com"},
    headers={"Authorization": "Bearer ar_your_key_here"},
)

data = response.json()
print(f"Score: {data['score']}/100 (Grade: {data['grade']})")

README Badge

[![GlobalDex](https://globaldex.ai/api/v1/badge?domain=your-domain.com)](https://globaldex.ai/sites)

CI/CD Pipeline

# GitHub Actions
- name: Check Agent-Readiness
  run: |
    SCORE=$(curl -s -X POST https://globaldex.ai/api/v1/scan \
      -H "Content-Type: application/json" \
      -d '{"url": "${{ env.DEPLOY_URL }}"}' | jq '.score')
    echo "Agent-Readiness Score: $SCORE/100"
    if [ "$SCORE" -lt 50 ]; then
      echo "::warning::Low agent-readiness score: $SCORE/100"
    fi

Error Codes

StatusMeaning
200Success
400Bad request — invalid URL or missing parameters
401Unauthorized — invalid API key
404Not found — domain has not been scanned
429Rate limit exceeded
502Scan failed — target site error
504Scan timed out