Ailysi Design Engine · API Layer

Design API Layer

A versioned, token-authenticated REST + webhook surface that exposes every Design Engine capability — token resolution, brand synthesis, component generation, governance audit, memory, and cross-OS distribution.

REST + WebhooksVersioned /v1Bearer AuthIdempotentTiered Rate Limits

Base URL

https://api.ailysi.com
Versioning: /v1 path prefix · Accept-Version header for opt-in v2 · deprecations announced 90 days out.

Authentication & Access

Bearer API Key

Per-tenant API key. Header: Authorization: Bearer de_live_xxx.

scopes: tokens, brands, components, governance, memory

OAuth2 (platform)

For platform-level integrations (Ailysi marketplace, partner apps).

scopes: admin:all

Session (UI)

Frontend calls from the Ailysi app reuse the logged-in user session.

scopes: inherits user RLS

tokens:readtokens:writebrands:readbrands:writecomponents:syncgovernance:auditmemory:readmemory:writedistribution:push

Endpoint Registry

Tokens

4 routes
POST
/v1/tokens

Generate a token set from a tenant theme manifest

tokens:write
GET
/v1/tokens/:tenant_id

Resolve the live token set for a tenant (dark/light)

tokens:read
PUT
/v1/tokens/:tenant_id

Override individual tokens (pin or mutate)

tokens:write
POST
/v1/tokens/:tenant_id/pin

Pin a token — freeze it from auto-evolution

tokens:write

Brands

5 routes
POST
/v1/brands

Create brand identity via AI palette + typography synthesis

brands:write
GET
/v1/brands/:id

Retrieve a brand profile + resolved tokens

brands:read
PATCH
/v1/brands/:id

Update brand config (tone, palette, fonts)

brands:write
POST
/v1/brands/:id/logo

Generate logo candidates via AI image synthesis

brands:write
GET
/v1/brands/:id/compliance

Brand compliance scorecard (contrast, usage, clear-space)

governance:audit

Components

3 routes
POST
/v1/components

Generate a component variant spec from tokens

components:sync
GET
/v1/components/:id

Retrieve a stored variant spec

tokens:read
POST
/v1/components/bulk

Bulk-sync multiple variant specs

components:sync

Layouts

2 routes
POST
/v1/layouts/:vertical/resolve

Resolve a page skeleton for a tenant vertical

tokens:read
POST
/v1/layouts/compose

Compose a full landing from section blocks

tokens:read

Governance

4 routes
POST
/v1/governance/audit

Run all 4 AEON-Design gates on a rendered surface

governance:audit
GET
/v1/governance/audit/:id

Retrieve an audit result + gate breakdown

governance:audit
GET
/v1/governance/drift/:tenant_id

Snapshot diff vs last known-good baseline

governance:audit
POST
/v1/governance/approve

Approve a high-risk BrandChangeRequest

brands:write

Memory

4 routes
POST
/v1/memory

Record a design learning (pillar↔engagement correlation)

memory:write
GET
/v1/memory/:tenant_id

List stored learnings for a tenant

memory:read
POST
/v1/memory/evolve

Propose token micro-adjustments from memory

memory:write
POST
/v1/memory/ab

Ship + score a design variant A/B test

memory:write

Distribution

2 routes
POST
/v1/distribute

Federate a content/brand asset across OS modules

distribution:push
GET
/v1/distribution/:asset_id

Retrieve the per-OS distribution manifest

tokens:read

Hand-off

2 routes
GET
/v1/handoff/:tenant_id

Export the design hand-off pack (tokens + components)

tokens:read
GET
/v1/handoff/:tenant_id/figma

Figma-mirror export bundle

tokens:read

Webhooks

brand.created

A new brand identity was AI-synthesized and persisted

brands
brand.updated

Brand config (palette, tone, fonts) changed

brands
logo.generated

Logo candidates were synthesized

brands
governance.passed

A rendered surface passed all AEON-Design gates

governance
governance.blocked

A gate blocked output (brand, a11y, drift)

governance
memory.learned

A new design learning was recorded

memory
evolution.proposed

Token micro-adjustment proposed by auto-evolution

memory
distribution.complete

Cross-OS asset federation finished

distribution

Webhooks signed with HMAC-SHA256 via X-Ailysi-Signature header. Retry: exponential backoff, 24h max.

Rate Limits

Starter

100

req/min · burst 20

Solo founder / single brand

Pro

1000

req/min · burst 100

Growing team, multiple brands

Studio

10000

req/min · burst 500

Agencies, multi-brand operators

Enterprise

Unlimited

req/min · burst —

Platform / white-label SaaS

Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. 429 on exceed.

Error Model

{
  "error": {
    "code": "governance_blocked",
    "message": "Output failed the accessibility gate: contrast 3.2:1 below WCAG AA 4.5:1.",
    "details": {
      "gate": "accessibility",
      "violations": [
        { "token": "--text-body", "ratio": 3.2, "required": 4.5 }
      ]
    },
    "request_id": "req_8f3a2b"
  }
}

Every error returns HTTP 4xx/5xx + a consistent envelope. request_id enables trace lookup in GovernanceAuditLog.

Quick Start · cURL

# Generate a brand identity
curl -X POST https://api.ailysi.com/v1/brands \
  -H "Authorization: Bearer de_live_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c1f2a7e-3b4d-4e5f-8a9b" \
  -d '{
    "name": "Acme Labs",
    "industry": "logistics",
    "mood": "confident",
    "auto_logo": true
  }'

SDK Clients

JavaScript

npm i @ailysi/design-engine

Typed, tree-shakeable, auto-retry on 429

Python

pip install ailysi-design-engine

Async + sync clients, dataclasses

cURL / HTTP

any HTTP client

Raw REST — see quick start above

One surface, every capability

The API mirrors the 5-layer architecture 1:1 — tokens, brands, components, governance, memory, distribution — so any external app can drive the Design Engine the same way the Ailysi frontend does.