AllGoodInsp API

openapi: 3.1.0
info:
  title: AllGoodInsp API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 18 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; AllGoodInsp has published no machine-readable contract that the
    pipeline could find. Engine: oss.'
  x-evidence-tiers:
    code-example: 3
    documentation: 15
    pages-with-code: 2
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: oss
  x-sources:
  - https://allgoodinsp.com/docs/api
  - https://allgoodinsp.com/docs/mcp
servers:
- url: https://api.allgoodinsp.com
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://allgoodinsp.com/docs/mcp
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: http https://mcp.allgoodinsp.com \
  /api-keys:
    get:
      operationId: get_api_keys
      tags:
      - Api Keys
      summary: List all API keys for the authenticated user.
      x-source: https://allgoodinsp.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeysResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_keys
      tags:
      - Api Keys
      summary: Create a new API key.
      x-source: https://allgoodinsp.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiKeysRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiKeysResponse'
      x-evidence:
        kind: documentation
  /api-keys/{id}:
    delete:
      operationId: delete_api_keys_id
      tags:
      - Api Keys
      summary: Revoke an API key.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiKeysIdResponse'
      x-evidence:
        kind: documentation
  /extract-essence:
    post:
      operationId: post_extract_essence
      tags:
      - Extract Essence
      summary: The primary synthesis endpoint.
      x-source: https://allgoodinsp.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostExtractEssenceRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExtractEssenceResponse'
      x-evidence:
        kind: documentation
  /screenshots/{siteId}:
    get:
      operationId: get_screenshots_siteId
      tags:
      - Screenshots
      summary: Retrieve a screenshot of the site as a WebP image.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      - name: size
        in: query
        required: false
        schema:
          type: string
        description: 'full for the full viewport screenshot (default: thumbnail)'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /search:
    get:
      operationId: get_search
      tags:
      - Search
      summary: Semantic search across all sites.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query (e.g. minimal editorial typography)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 'Max results, 1–30 (default: 20)'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSearchResponse'
      x-evidence:
        kind: documentation
  /sites:
    get:
      operationId: get_sites
      tags:
      - Sites
      summary: List all sites with optional filters and pagination.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: Filter by category (e.g. software-saas, agency)
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Filter by ISO 3166-1 alpha-2 code (e.g. JP, US)
      - name: region
        in: query
        required: false
        schema:
          type: string
        description: Filter by region (e.g. east-asia, europe)
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: 'Page number (default: 1)'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 'Results per page, 1–100 (default: 30)'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesResponse'
      x-evidence:
        kind: documentation
  /sites/{siteId}:
    get:
      operationId: get_sites_siteId
      tags:
      - Sites
      summary: Retrieve the full design analysis for a single site.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesSiteidResponse'
      x-evidence:
        kind: documentation
  /submissions:
    post:
      operationId: post_submissions
      tags:
      - Submissions
      summary: Submit a site URL for review.
      x-source: https://allgoodinsp.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSubmissionsRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSubmissionsResponse'
      x-evidence:
        kind: documentation
  /taxonomy:
    get:
      operationId: get_taxonomy
      tags:
      - Taxonomy
      summary: Get all categories, countries, and regions with site counts.
      x-source: https://allgoodinsp.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTaxonomyResponse'
      x-evidence:
        kind: documentation
  /v1/api-keys:
    get:
      operationId: get_v1_api_keys
      tags:
      - Api Keys
      summary: List all API keys for the authenticated user.
      x-source: https://allgoodinsp.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ApiKeysResponse'
      x-evidence:
        kind: documentation
  /v1/extract-essence:
    post:
      operationId: post_v1_extract_essence
      tags:
      - Extract Essence
      summary: POST /v1/extract-essence
      x-source: https://allgoodinsp.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ExtractEssenceRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ExtractEssenceResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST "https://api.allgoodinsp.com/v1/extract-essence"  -H "Authorization: Bearer YOUR_API_KEY"  -H "Content-Type: application/json"  -d
          ''{"site_ids": ["<id-1>", "<id-2>"], "brief": "SaaS landing page, bold typography"}'' 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 p'
  /v1/screenshots/stripe-com:
    get:
      operationId: get_v1_screenshots_stripe_com
      tags:
      - Screenshots
      summary: Retrieve a screenshot of the site as a WebP image.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: size
        in: query
        required: false
        schema:
          type: string
        description: 'size full for the full viewport screenshot (default: thumbnail)'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/search:
    get:
      operationId: get_v1_search
      tags:
      - Search
      summary: Semantic search across all sites.
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Search query (e.g. minimal editorial typography )
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 'Max results, 1–30 (default: 20 )'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SearchResponse'
      x-evidence:
        kind: documentation
  /v1/sites:
    get:
      operationId: get_v1_sites
      tags:
      - Sites
      summary: GET /v1/sites
      x-source: https://allgoodinsp.com/docs/api
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SitesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl "https://api.allgoodinsp.com/v1/sites?limit=3" Then sign in , click New Key on your account page, and check the key (free,
          no credits used): curl "https://api.allgoodinsp.com/v1/credits"  -H "Authorization: Bearer YOUR_API_KEY" Search for references, then
          synthesize the top hits into a DESIGN.md: curl "https://api.allgoodinsp.com/v1/search?q=saas+landing+bold+typography&limit=3"  -H "Authoriz'
  /v1/sites/stripe-com:
    get:
      operationId: get_v1_sites_stripe_com
      tags:
      - Sites
      summary: Retrieve the full design analysis for a single site.
      x-source: https://allgoodinsp.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SitesStripeComResponse'
      x-evidence:
        kind: documentation
  /v1/taxonomy:
    get:
      operationId: get_v1_taxonomy
      tags:
      - Taxonomy
      summary: Get all categories, countries, and regions with site counts.
      x-source: https://allgoodinsp.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1TaxonomyResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiKeysResponse:
      type: object
      properties:
        keys:
          type: array
          description: Array of API key metadata objects
    PostApiKeysRequest:
      type: object
      properties:
        name:
          type: string
          description: A label for the key (max 100 characters)
      required:
      - name
    PostApiKeysResponse:
      type: object
      properties:
        id:
          type: string
          description: Key identifier
        key:
          type: string
          description: Full API key (shown only once)
        keyPrefix:
          type: string
          description: Prefix of the key
        name:
          type: string
          description: Label of the key
        createdAt:
          type: string
          description: Creation timestamp
    DeleteApiKeysIdResponse:
      type: object
      properties:
        revoked:
          type: boolean
          description: Indicates revocation success
    PostExtractEssenceRequest:
      type: object
      properties:
        site_ids:
          type: array
          description: Array of 2-5 site IDs (from /search results)
        brief:
          type: string
          description: Design goal, min 10 characters
        aspect_overrides:
          type: object
          description: Map of color / typography / layout / sections to a site_id
        reference_intents:
          type: array
          description: Array of { site_id, take, leave? } indicating what to adopt or avoid per reference
      required:
      - site_ids
      - brief
    PostExtractEssenceResponse:
      type: object
      properties:
        site_ids:
          type: array
          description: Echoed site IDs
        format:
          type: string
          description: Output format (design-md)
        filename_hint:
          type: string
          description: Suggested filename
        brief:
          type: string
          description: Generated DESIGN.md content
        credits:
          type: object
          description: Remaining credit balances
    GetSearchResponse:
      type: object
      properties:
        query:
          type: string
          description: Echoed search query
        sites:
          type: array
          description: Matching site references
        total:
          type: integer
          description: Total number of matches
        next_step:
          type: object
          description: Suggested next step for synthesis
    GetSitesResponse:
      type: object
      properties:
        sites:
          type: array
          description: Array of site objects
        pagination:
          type: object
          description: Pagination info
    GetSitesSiteidResponse:
      type: object
      properties:
        meta:
          type: object
          description: Metadata about the site
        convention_breaks:
          type: array
          description: List of convention breaks
        sections:
          type: array
          description: Design sections and components
    PostSubmissionsRequest:
      type: object
      properties:
        url:
          type: string
          description: The site URL (must be http or https)
        siteName:
          type: string
          description: Optional site name (max 200 characters)
        description:
          type: string
          description: Optional description or notes (max 2000 characters)
      required:
      - url
    PostSubmissionsResponse:
      type: object
      properties:
        id:
          type: string
          description: Submission identifier
        status:
          type: string
          description: Current status (e.g., pending)
    GetTaxonomyResponse:
      type: object
      properties:
        categories:
          type: array
          description: Category objects with counts
        countries:
          type: array
          description: Country objects with counts
        regions:
          type: array
          description: Region objects with counts
    GetV1ApiKeysResponse:
      type: object
      properties:
        keys:
          type: array
    PostV1ExtractEssenceRequest:
      type: object
      properties:
        site_ids:
          type: array
          items:
            type: string
        brief:
          type: string
    PostV1ExtractEssenceResponse:
      type: object
      properties:
        sites:
          type: array
          items:
            type: object
            properties:
              site_id:
                type: string
              site_name:
                type: string
              url:
                type: string
              category:
                type: string
              country:
                type: string
              region:
                type: string
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            total_pages:
              type: integer
    GetV1SearchResponse:
      type: object
      properties:
        query:
          type: string
        sites:
          type: array
        total:
          type: integer
        next_step:
          type: object
    GetV1SitesResponse:
      type: object
      properties:
        sites:
          type: array
          items:
            type: object
            properties:
              site_id:
                type: string
              site_name:
                type: string
              url:
                type: string
              category:
                type: string
              country:
                type: string
              region:
                type: string
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            total_pages:
              type: integer
    GetV1SitesStripeComResponse:
      type: object
      properties:
        meta:
          type: object
        convention_breaks:
          type: array
        sections:
          type: array
    GetV1TaxonomyResponse:
      type: object
      properties:
        categories:
          type: array
        countries:
          type: array
        regions:
          type: array
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Api Keys
- name: Extract Essence
- name: Screenshots
- name: Search
- name: Sites
- name: Submissions
- name: Taxonomy