Ensemble API

11 interconnected design tools as a unified API. Generate complete, production-ready design systems from a single hex color. Pure computation - no AI, no external dependencies, deterministic output.

Every tool's output feeds the next. Colors inform shadows. Typography informs spacing. Spacing informs grids. All of it flows into component patterns and exports.

Quickstart

Generate a full design system with one request:

curl -X POST https://api.ensemble.hearthbyte.dev/v2/design-system \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seed": {
      "colors": ["#3B82F6"],
      "mood": "professional",
      "preferences": {
        "color_scheme": "analogous",
        "dark_mode": true
      }
    },
    "formats": ["css", "json"]
  }'

Response includes 15 top-level keys with everything you need:

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer ens_live_xxxxxxxxxxxxxxxxxxxx

Key Types

Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1771034953

Client keys (ens_pub_) receive 50% of the tier's server key limits.

WebMCP

Ensemble exposes all 9 tools via WebMCP — a browser-native protocol that lets AI agents discover and invoke tools directly on the page. No API key needed for client-side use.

Discovery

Agents discover available tools from the manifest:

GET /.well-known/webmcp.json

Returns the full schema for all 9 tools — names, descriptions, and input schemas.

Runtime API

On any Ensemble tool page, the runtime is available at window.ensembleTools:

// List all registered tools
const tools = window.ensembleTools.list();

// Invoke a tool by name
const result = await window.ensembleTools.invoke('harmony', {
  hex: '#3B82F6'
});

// Get full schema (all tools + metadata)
const schema = window.ensembleTools.schema();

Each invoke() returns a result object:

{
  "content": [
    { "type": "text", "text": "{ ... JSON result ... }" }
  ]
}

Available Tools

Example

// Generate a palette and use it
const result = await window.ensembleTools.invoke('harmony', {
  hex: '#3B82F6'
});

const palette = JSON.parse(result.content[0].text);
console.log(palette.swatches); // Array of generated colors

Unified Design System

Request Body

{
  "seed": {
    "colors": ["#3B82F6"],        // 1-5 hex colors (required)
    "mood": "professional",       // optional: professional|playful|bold|calm|warm|cool
    "industry": "saas",           // optional: healthcare|fintech|saas|ecommerce|creative|...
    "preferences": {
      "color_scheme": "analogous",  // monochromatic|analogous|complementary|triadic|split-complementary
      "type_style": "modern",      // modern|classical|minimalist|expressive
      "density": "balanced",        // compact|balanced|airy
      "corners": "rounded",         // sharp|rounded|pill
      "shadow_intensity": "subtle", // flat|subtle|pronounced|dramatic
      "animation_style": "minimal", // none|minimal|fluid|energetic
      "dark_mode": true             // include dark mode variant
    },
    "accessibility": {
      "wcag_level": "AA",          // AA or AAA
      "min_contrast": 4.5           // 1-21
    }
  },
  "formats": ["css", "json"]     // All 4 formats available with Pro
}

Only seed.colors is required. Everything else has sensible defaults.

Individual Tools

Call any tool independently. Tools that depend on upstream data will auto-generate it from the seed.

Harmony - Color Palette

{
  "seed": {
    "colors": ["#E74C3C"],
    "preferences": { "color_scheme": "triadic" }
  }
}

Writes: colors - primary, secondary, accent (if triadic+), neutral, semantic (success/warning/error/info). Each with 50-950 shade scale.

Duet - Font Pairing

Writes: typography - heading, body, mono font families. Type scale with sizes from xs to 5xl, line heights, and letter spacing.

Pitch - Contrast Validation

Single pair mode:

{
  "foreground": "#3B82F6",
  "background": "#FFFFFF"
}

Full audit: Pass a seed with colors. Returns contrast matrix for 60+ meaningful combinations with fix suggestions for failures.

Writes: accessibility - audit stats, contrast matrix, failures with OKLCH fix suggestions, text color recommendations.

Tempo - Spacing

Writes: spacing - base unit, scale values, density-aware adjustments.

Chord - Shadows

Writes: shadows - elevation levels (xs through 2xl), focus ring, glow effect.

Cadence - Grids

Writes: grid - breakpoints, columns, container widths, gutter sizes.

Riff - Animation

Writes: animations - duration scale, easing functions, named presets (fade, slide, scale, bounce).

Bridge - Dark Mode

Writes: dark_mode - transformed colors, shadows, spacing adjustments, re-validated accessibility.

Motif - Components

Writes: components - 7 component types with variants (primary, secondary, ghost, danger buttons; default, elevated, interactive cards; etc.).

Score - Icons

Writes: icons - recommended library, install instructions, size guidelines, color integration config.

Compose - Export

{
  "seed": { "colors": ["#3B82F6"] },
  "formats": ["css", "json", "tailwind", "scss"]
}

All four formats included with Pro: CSS, JSON, Tailwind, SCSS.

Utility Endpoints

Error Handling

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "invalid_input",
    "message": "seed.colors must have at least one color",
    "status": 400
  }
}

Pricing

API access requires a Pro subscription. All 11 tools, all export formats, full /design-system pipeline.

The browser-based tools at hearthbyte.dev/ensemble are free to use without an account.

Try It

Test the API right here. Uses the public demo endpoint - no key required. 5 requests per minute.