API Reference

Generation API

Integrate the most capable frontend design engine directly into your applications, CI pipelines, or internal tools.

Architecture Decision: REST API vs MCP

AIDesigner exposes two programmatic surfaces. Choose the REST API when your own service should make HTTP requests. Choose MCP when a coding assistant should call AIDesigner directly through OAuth and tool use.

REST API

Language-agnostic HTTP endpoints for backend services, queued jobs, CI, or internal tools.

Authenticate with API keys
Works from any runtime
Best when you own the request lifecycle

MCP Server

OAuth-backed tool integration for Claude Code, Codex, Cursor, VS Code, and Windsurf.

No API key handling in your app
Native assistant tool calling
Best for repo-aware interactive workflows

Read MCP docs

Authentication

The REST API uses bearer authentication. Provision API keys from Settings → API Keys, copy the full secret when it is created, and send it in the Authorization header for each request.

Authorization Header

Authorization: Bearer gp_your_secret_api_key

Never expose secret keys in client-side code. If you want your assistant to authenticate directly, use MCP and OAuth instead of embedding API keys.

Rate Limits

REST generation traffic is limited per authenticated account. API keys created under the same account share one REST budget, which prevents key rotation from bypassing the cap.

Limit	Default	Scope
Generation requests	30 / 60s	Shared across all API keys on the same account
Concurrent generations	4 in flight	Shared across all API keys on the same account

Successful requests include standard rate-limit headers so callers can back off proactively. When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Rate-Limit Headers

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1775476860
X-RateLimit-Window: 60
X-RateLimit-Policy: 30;w=60
X-RateLimit-Concurrency-Limit: 4

/generateDesign

POST/api/v1/generateDesign

Generates a single-file HTML interface from either a prompt or a multi-turn message history. Website analysis can be enabled by passing a mode and source URL.

Request Body

prompt Required unless messages is provided	string Single-turn natural language description of the interface you want to generate.
messages Required unless prompt is provided	array Conversation history for iterative refinement and multi-step design generation.
streaming Optional · Default true	boolean Return OpenAI-style server-sent event chunks when true, or a single JSON payload when false.
mode Optional	enum Website analysis mode: inspire, clone, or enhance.
url Required when mode is set	string Reference URL to scrape and analyze before generation.

curl -X POST https://api.aidesigner.ai/api/v1/generateDesign \
  -H "Authorization: Bearer $AIDESIGNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A modern dashboard with account balances, charts, and recent activity",
    "streaming": false
  }'

Website Analysis Modes

When you include both mode and url, AIDesigner scrapes the target page before generation.

inspire

Borrow the brand feel while allowing more creative freedom in layout and structure.

clone

Aim for a close recreation of the reference layout, spacing, and visual treatment.

enhance

Preserve the original content while improving presentation and overall polish.

Response & Credits

Streaming is the default. Use server-sent events when you want incremental HTML output, or set streaming: false for one JSON response. Each request costs at least one credit. Website analysis modes charge an extra credit for the scrape and analysis step.

Streaming Response

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"<!DOCTYPE html>..."},"finish_reason":null}]}
data: [DONE]

JSON Response

{
  "success": true,
  "content": "<!DOCTYPE html>...",
  "usage": {
    "prompt_tokens": 1234,
    "completion_tokens": 5678,
    "total_tokens": 6912
  }
}

Error Codes

Standard HTTP status codes are used. Authentication, malformed payloads, and insufficient-credit failures happen before generation begins.

Status	Meaning
400	Invalid JSON, missing prompt/messages, or missing URL when website analysis is enabled.
401	Missing, malformed, revoked, or invalid API key.
403	The account does not have enough credits for the request.
429	The account exceeded the request window or already has too many in-flight generations. Check `Retry-After` and the `X-RateLimit-*` headers before retrying.
500 / 502	Internal generation or upstream model failure.