REST API

The AllGoodInsp REST API provides programmatic access to the same design reference data available via MCP. All endpoints return JSON and support CORS.

Base URL

https://allgoodinsp.com/api/v1

Authentication

Most read endpoints work without authentication, subject to stricter rate limits. For higher limits and write access, generate an API key from your account page and include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Unauthenticated 5 req/hour, 10/day (general). 3 req/hour, 5/day (search). No submissions.

Authenticated 10 req/min, 50/day (general). 5 req/min, 25/day (search). 5 req/hour, 3/day (submissions).

Endpoints

GET /sites

List all sites with optional filters and pagination.

Query parameters

category Filter by category (e.g. software-saas, agency)

country Filter by ISO 3166-1 alpha-2 code (e.g. JP, US)

region Filter by region (e.g. east-asia, europe)

page Page number (default: 1)

limit Results per page, 1–100 (default: 30)

Example

curl "https://allgoodinsp.com/api/v1/sites?category=agency&country=JP&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "sites": [
    {
      "site_id": "example-agency",
      "site_name": "Example Agency",
      "url": "https://example-agency.com/",
      "category": "agency",
      "country": "JP",
      "region": "east-asia"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

GET /sites/:site_id

Retrieve the full design analysis for a single site. Includes sections, components, CSS values, and principle references. AI-only fields (mood, user_might_say, etc.) are stripped.

Example

curl "https://allgoodinsp.com/api/v1/sites/stripe-com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "meta": {
    "site_id": "stripe-com",
    "site_name": "Stripe",
    "url": "https://stripe.com/",
    "category": "software-saas",
    "country": "US",
    "region": "north-america"
  },
  "convention_breaks": [...],
  "sections": [
    {
      "section": "hero",
      "role": "...",
      "dominant_decision": "...",
      "components": [
        {
          "target": "Hero Headline",
          "principle_refs": ["typo_002", "layout_003"],
          "what": "...",
          "css": "...",
          "why": "..."
        }
      ]
    }
  ]
}

GET /search

Semantic search across all sites. Matches against mood, purpose, and design descriptions using vector embeddings.

q Required. Search query (e.g. minimal editorial typography)

limit Max results, 1–30 (default: 20)

Example

curl "https://allgoodinsp.com/api/v1/search?q=bold+typography+dark+theme&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "query": "bold typography dark theme",
  "sites": [
    {
      "site_id": "example-site",
      "site_name": "Example Site",
      "url": "https://example-site.com/",
      "category": "portfolio",
      "country": "US",
      "region": "north-america"
    }
  ],
  "total": 5
}

GET /taxonomy

Get all categories, countries, and regions with site counts. Useful for building filter UIs.

Example

curl "https://allgoodinsp.com/api/v1/taxonomy" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "categories": [
    { "category": "agency", "count": 120 },
    { "category": "software-saas", "count": 95 }
  ],
  "countries": [
    { "country": "JP", "count": 380 },
    { "country": "US", "count": 170 }
  ],
  "regions": [
    { "region": "east-asia", "count": 385 },
    { "region": "north-america", "count": 172 }
  ]
}

GET /screenshots/:site_id

Retrieve a screenshot of the site as a WebP image.

size full for the full viewport screenshot (default: thumbnail)

Example

curl "https://allgoodinsp.com/api/v1/screenshots/stripe-com?size=full" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o screenshot.webp

Returns image/webp with a 24-hour cache header. Returns 404 if no screenshot is available.

POST /submissions

Submit a site URL for review. Submissions enter a moderation queue and are not published immediately. Rate limited to 5 requests per hour.

Request body

url Required. The site URL (must be http or https)

siteName Optional site name (max 200 characters)

description Optional description or notes (max 2000 characters)

Example

curl -X POST "https://allgoodinsp.com/api/v1/submissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "siteName": "Example Site"}'

Response

{
  "id": "a1b2c3d4-...",
  "status": "pending"
}

Returns 409 if the URL already exists in the collection or is already pending review.

Errors

All errors return JSON with an error field:

{ "error": "Site not found" }

400 Bad request (missing or invalid parameters)

401 Invalid or expired API key, or authentication required (submissions)

429 Rate limit exceeded

404 Resource not found

405 Method not allowed

409 Duplicate resource (URL already exists or pending)

Rate limits

Limits depend on whether you include an API key:

Authenticated 10/min + 50/day general, 5/min + 25/day search, 5/hour + 3/day submissions

Unauthenticated 5/hour + 10/day general, 3/hour + 5/day search (IP-based)

Rate limit status is returned in response headers:

X-RateLimit-Limit Maximum requests allowed in the window

X-RateLimit-Remaining Requests remaining in the current window

X-RateLimit-Reset Seconds until the window resets

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.