Skip to main content
GlobalDex
REST API v1

API Documentation

Use GlobalDex to enforce agent-readiness in CI/CD pipelines, monitoring dashboards, and automated compliance workflows.

Quick Start

All API v1 endpoints require an API key. Include it in theAuthorization header as a Bearer token.

# Scan a URL (API key required)
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)
environmentstringoptional'production' | 'staging' | 'development' (default: production)
thresholdnumberoptionalOptional policy threshold override (0-100)

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,
    "webmcp_compatibility": "current",
  "checks_passed": 22,
  "checks_total": 34,
  "categories": [
    {
      "name": "structure",
      "label": "Structure",
      "score": 20,
      "max_score": 25,
      "percentage": 80,
      "checks": [...]
    }
  ],
    "scanned_at": "2026-02-18T...",
    "policy_gate": {
        "environment": "production",
        "threshold": 80,
        "status": "pass",
        "message": "Score 80 meets threshold 80 for production"
    },
    "regression": {
        "delta": -6,
        "previousScore": 86,
        "currentScore": 80,
        "severity": "minor",
        "alert": true
    }
}
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": 22,
  "checks_total": 34,
  "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" />
GET/api/v1/report?domain=stripe.com

Compliance Report Export

Export a machine-readable compliance report (checks, categories, policy gate, regression, evidence metadata).

Query Parameters

NameTypeRequiredDescription
domainstringrequiredDomain to export report for

Example

curl https://globaldex.ai/api/v1/report?domain=stripe.com \
  -H "Authorization: Bearer ar_your_key_here"

Response

{
  "report_version": "1.0",
  "generated_at": "2026-03-07T...",
  "domain": "stripe.com",
  "scan_id": "a1b2c3d4-...",
  "score": 80,
  "grade": "B",
  "webmcp_compatibility": "mixed",
  "policy_gate": { ... },
  "regression": { ... },
  "category_scores": [ ... ],
  "checks": [ ... ],
  "evidence": {
    "control_set": "GlobalDex-34"
  }
}

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 Deployment Gate

# GitHub Actions — block deploy if not agent-ready
- name: Agent-Readiness Gate
  uses: S-Borna/globaldex-action@v1
  with:
    url: "${{ env.DEPLOY_URL }}"
    threshold: 60

# Or use the CLI directly
- name: Agent-Readiness Gate
  run: npx globaldex-cli scan ${{ env.DEPLOY_URL }} --threshold 60

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