REST API

GET /sites

List all sites with optional filters and pagination.

Query parameters

Example

curl "https://api.allgoodinsp.com/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://api.allgoodinsp.com/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.

Example

curl "https://api.allgoodinsp.com/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://api.allgoodinsp.com/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.

Example

curl "https://api.allgoodinsp.com/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

Example

curl -X POST "https://api.allgoodinsp.com/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.

POST /api-keys

Create a new API key. Requires authentication. Maximum 5 active keys per user.

Request body

Example

curl -X POST "https://api.allgoodinsp.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

Response

{
  "id": "a1b2c3d4-...",
  "key": "agi_...",
  "keyPrefix": "agi_abcd",
  "name": "Production",
  "createdAt": "2026-03-26T00:00:00.000Z"
}

The key field contains the full API key and is shown only once. Store it securely.

GET /api-keys

List all API keys for the authenticated user. Full keys are never returned — only the prefix for identification.

Example

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

Response

{
  "keys": [
    {
      "id": "a1b2c3d4-...",
      "keyPrefix": "agi_abcd",
      "name": "Production",
      "createdAt": "2026-03-26T00:00:00.000Z",
      "lastUsedAt": "2026-03-26T12:00:00.000Z",
      "revokedAt": null
    }
  ]
}

DELETE /api-keys/:id

Revoke an API key. The key becomes immediately unusable. This cannot be undone.

Example

curl -X DELETE "https://api.allgoodinsp.com/v1/api-keys/a1b2c3d4-..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{ "revoked": true }