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"

No key required and no rate limit on this endpoint. A key is needed for /sites/:site_id, /extract-essence and /submissions, and raises the limit on /search.

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. Requires an API key and costs 1 credit (same as MCP get_site). Charged responses include X-Credits-Free-Remaining / X-Credits-Paid-Remaining headers.

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,
  "next_step": {
    "description": "Synthesize 2-5 of these references into a ready-to-save DESIGN.md...",
    "endpoint": "POST /v1/extract-essence",
    "example_body": { "site_ids": ["<site_id>", "<site_id>", "<site_id>"], "brief": "<your design goal>" },
    "cost_credits": 5
  }
}

POST /extract-essence

The primary synthesis endpoint. Combines 2-5 references into a ready-to-save DESIGN.md: YAML design tokens, CSS custom properties, color palette, typography scale, spacing system, motion notes, section structure, and binding do's-and-don'ts. Save the returned brief as DESIGN.md at your project root and reference it from CLAUDE.md/AGENTS.md so it loads on every generation. Requires an API key. Costs 5 credits — only charged when synthesis succeeds (invalid input and unknown site_ids are free).

Example

curl -X POST "https://api.allgoodinsp.com/v1/extract-essence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_ids": ["example-site", "another-site", "third-site"],
    "brief": "SaaS landing page for a developer tool, confident and minimal"
  }'

Response

{
  "site_ids": ["example-site", "another-site", "third-site"],
  "format": "design-md",
  "filename_hint": "DESIGN.md",
  "brief": "---\nname: ...\ncolors: ...\n---\n\n# Design System\n\n**Goal**: SaaS landing page...\n\n## CSS Custom Properties\n...",
  "credits": { "free_remaining": 70, "paid_remaining": 0 }
}

Unknown site_ids return 404 with suggested alternatives matching your brief. Insufficient credits return 402.

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. All keys start with agi_; keys created on the account page before 2026-08-24 start with allgoodinsp_ and keep working. Both prefixes work on every endpoint and on MCP.

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 }