# genui.sh - Full API Documentation

> genui.sh is an API service that turns JSON into hosted, shareable UI artifacts (charts, tables, markdown, PDFs, dynamic UIs). Built for AI agents and developers who need to render and share data visualizations with a single API call.

## API Base URL

```
https://www.genui.sh/api
```

## Authentication

All API requests require an API key in the Authorization header:

```
Authorization: Bearer art_live_xxxxxxxxxxxxx
```

Get your API key at: https://www.genui.sh/dashboard

---

## Endpoints

### Create Artifact

**POST /api/artifacts**

Creates a new artifact and returns metadata including the shareable URL.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| template | string | Yes | One of: `chart`, `table`, `markdown`, `pdf`, `@std/dynamic` |
| title | string | No | Display title (max 255 chars) |
| content | object | Yes | Template-specific content object |
| expiresIn | string | No | Duration like `7d`, `24h`, `30m`, `60s` |
| expiresAt | string | No | ISO 8601 datetime |

#### Response

```json
{
  "data": {
    "id": "abc123",
    "template": "chart",
    "title": "Sales Dashboard",
    "viewCount": 0,
    "status": "active",
    "expiresAt": "2024-02-01T00:00:00Z",
    "createdAt": "2024-01-25T00:00:00Z"
  }
}
```

The artifact is viewable at: `https://www.genui.sh/a/{id}`

---

### List Artifacts

**GET /api/artifacts**

Returns paginated list of your artifacts.

#### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | number | 1 | Page number |
| limit | number | 20 | Items per page (max 100) |
| template | string | - | Filter by template type |
| status | string | active | Filter: `active`, `expired`, `all` |

#### Response

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

---

### Get Artifact

**GET /api/artifacts/{id}**

Returns full artifact details including content.

---

### Update Artifact

**PATCH /api/artifacts/{id}**

Updates an existing artifact.

#### Request Body

| Field | Type | Description |
|-------|------|-------------|
| title | string | New title |
| content | object | New content |
| expiresAt | string | New expiry datetime |

---

### Delete Artifact

**DELETE /api/artifacts/{id}**

Soft-deletes an artifact.

---

## Templates

### Chart Template

Create interactive charts with automatic legends, tooltips, and responsive sizing.

#### Content Schema

```json
{
  "type": "bar",
  "data": [
    { "name": "Jan", "revenue": 4000, "profit": 2400 },
    { "name": "Feb", "revenue": 3000, "profit": 1800 }
  ],
  "config": {
    "dataKeys": ["revenue", "profit"],
    "xKey": "name",
    "colors": ["#3b82f6", "#10b981"],
    "showGrid": true,
    "showLegend": true,
    "showTooltip": true,
    "title": "Monthly Revenue"
  }
}
```

#### Chart Types

- `line` - Line chart with smooth curves
- `bar` - Vertical bar chart
- `pie` - Pie/donut chart
- `area` - Filled area chart

#### Config Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| type | string | required | `line`, `bar`, `pie`, `area` |
| xKey | string | "name" | Key for x-axis labels |
| yKey | string | "value" | Key for y-axis values |
| dataKeys | string[] | [yKey] | Multiple data series |
| colors | string[] | default palette | Hex colors for series |
| showGrid | boolean | true | Show grid lines |
| showLegend | boolean | true | Show legend |
| showTooltip | boolean | true | Show hover tooltips |
| title | string | - | Chart title |

#### Example: Multi-Series Line Chart

```json
{
  "template": "chart",
  "title": "Sales Trends",
  "content": {
    "type": "line",
    "data": [
      { "month": "Jan", "sales": 4000, "returns": 400 },
      { "month": "Feb", "sales": 3000, "returns": 300 },
      { "month": "Mar", "sales": 5000, "returns": 250 }
    ],
    "config": {
      "xKey": "month",
      "dataKeys": ["sales", "returns"]
    }
  }
}
```

---

### Table Template

Create sortable, searchable, paginated tables with CSV export.

#### Content Schema

```json
{
  "columns": [
    { "header": "Order ID", "accessorKey": "id" },
    { "header": "Customer", "accessorKey": "customer" },
    { "header": "Amount", "accessorKey": "amount" },
    { "header": "Status", "accessorKey": "status" }
  ],
  "rows": [
    { "id": "ORD-001", "customer": "Acme Corp", "amount": "$1,250", "status": "completed" },
    { "id": "ORD-002", "customer": "Globex Inc", "amount": "$890", "status": "pending" }
  ],
  "config": {
    "pageSize": 10,
    "enableSorting": true,
    "enablePagination": true,
    "enableSearch": true,
    "enableExport": true
  }
}
```

#### Column Definition

| Field | Type | Description |
|-------|------|-------------|
| header | string | Display name |
| accessorKey | string | Key in row data |

#### Config Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| pageSize | number | 10 | Rows per page |
| enableSorting | boolean | true | Click headers to sort |
| enablePagination | boolean | auto | Show pagination controls |
| enableSearch | boolean | true | Show search box |
| enableExport | boolean | true | Show CSV export button |

---

### Markdown Template

Render formatted markdown with GitHub Flavored Markdown support.

#### Content Schema

```json
{
  "text": "# Weekly Summary\n\n## Key Metrics\n- **Revenue**: $142,000 (+12%)\n- **New Users**: 1,234\n\n## Highlights\n1. Launched new dashboard\n2. Reduced latency by 40%"
}
```

#### Supported Features

- Headers (h1-h6)
- Bold, italic, strikethrough
- Ordered and unordered lists
- Task lists with checkboxes
- Code blocks with syntax highlighting
- Tables (GFM)
- Blockquotes
- Links and images
- Horizontal rules

---

### PDF Template

Generate downloadable PDF documents from markdown content.

#### Content Schema

```json
{
  "text": "# Quarterly Report\n\nRevenue increased **23%** year-over-year.",
  "title": "Q4 Report",
  "pageSize": "A4"
}
```

#### Options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| text | string | required | Markdown content |
| title | string | - | PDF document title |
| pageSize | string | "A4" | `A4`, `LETTER`, `LEGAL` |

---

### Dynamic UI Template (@std/dynamic)

Build complex UIs using a declarative JSON component tree.

#### Content Schema

```json
{
  "root": "card",
  "elements": {
    "card": {
      "key": "card",
      "type": "Card",
      "props": { "title": "Contact Form" },
      "children": ["form"]
    },
    "form": {
      "key": "form",
      "type": "Stack",
      "props": { "direction": "vertical", "gap": "md" },
      "children": ["nameInput", "emailInput", "submitBtn"]
    },
    "nameInput": {
      "key": "nameInput",
      "type": "Input",
      "props": { "label": "Name", "placeholder": "Your name" }
    },
    "emailInput": {
      "key": "emailInput",
      "type": "Input",
      "props": { "label": "Email", "type": "email" }
    },
    "submitBtn": {
      "key": "submitBtn",
      "type": "Button",
      "props": { "text": "Submit", "variant": "primary" }
    }
  }
}
```

#### Element Structure

| Field | Type | Description |
|-------|------|-------------|
| key | string | Unique identifier |
| type | string | Component type |
| props | object | Component properties |
| children | string[] | Child element keys |

#### Available Components

**Layout:**
- `Card` - Container with optional title, subtitle, footer
- `Stack` - Flex container (direction: vertical/horizontal, gap: sm/md/lg)
- `Grid` - Grid layout (columns: 1-6, gap: sm/md/lg)

**Typography:**
- `Text` - Text with variants (default, muted, success, warning, error)
- `Heading` - Headings level 1-6

**Form:**
- `Input` - Text input (type: text/email/password/number)
- `Button` - Button (variant: primary/secondary/outline/ghost)
- `FormField` - Label + input wrapper

**Data Display:**
- `Table` - Data table with columns and rows
- `Chart` - Embedded chart component
- `Metric` - KPI display with label, value, trend
- `Badge` - Status badge (variant: default/success/warning/error)
- `Avatar` - User avatar with image or initials
- `Progress` - Progress bar (value: 0-100)
- `List` - Ordered/unordered lists

**Feedback:**
- `Alert` - Alert box (variant: info/success/warning/error)

**Navigation:**
- `Link` - Hyperlink
- `Tabs` - Tabbed content
- `Accordion` - Collapsible sections

**Other:**
- `Divider` - Horizontal rule with optional label
- `Markdown` - Render markdown content

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| API requests | 100/minute per user |
| Auth endpoints | 5/minute per IP |
| Artifact views | 1000/minute |

---

## Plan Limits

### Free Plan — $0/month
- 50 artifacts per month
- 1MB max payload
- 7-day link expiry
- Branded "Made with genui.sh" footer on hosted pages

### Starter Plan — $7/month
- 500 artifacts per month
- 5MB max payload
- 30-day link expiry
- No branding

### Pro Plan — $19/month
- 3,000 artifacts per month
- 10MB max payload
- No link expiry
- No branding
- Priority support

---

## Error Responses

All errors return JSON with this structure:

```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

### Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| UNAUTHORIZED | 401 | Missing or invalid API key |
| FORBIDDEN | 403 | Rate limit or quota exceeded |
| NOT_FOUND | 404 | Artifact not found |
| VALIDATION_ERROR | 400 | Invalid request body |
| SERVER_ERROR | 500 | Internal server error |

---

## Blog

Long-form posts on the design and use cases. Each post is also served as plain markdown at `{post-url}/raw`:

- [Generate a PDF from JSON with one API call](https://genui.sh/blog/pdf-from-json-one-api-call) — A practical look at PDF-generation APIs in 2026, why most force a template-editor workflow, and the one-call multi-format approach. ([raw markdown](https://genui.sh/blog/pdf-from-json-one-api-call/raw))
- [From n8n workflow to a hosted dashboard in under a minute](https://genui.sh/blog/n8n-workflow-hosted-dashboard) — How to take any n8n workflow output and turn it into a shareable dashboard link with a single HTTP Request node. ([raw markdown](https://genui.sh/blog/n8n-workflow-hosted-dashboard/raw))
- [Introducing @std/dynamic: a JSON format for composable dashboards](https://genui.sh/blog/introducing-std-dynamic) — The composable dashboard format powering genui.sh: shape, primitives, and design rationale (designed for LLM tool use). ([raw markdown](https://genui.sh/blog/introducing-std-dynamic/raw))

---

## Links

- Dashboard: https://www.genui.sh/dashboard
- Blog: https://genui.sh/blog
- Quickstart: https://www.genui.sh/docs/quickstart
- API Docs: https://www.genui.sh/docs
- Playground: https://www.genui.sh/dashboard/playground
- Chart Template: https://www.genui.sh/docs/templates/chart
- Table Template: https://www.genui.sh/docs/templates/table
- Markdown Template: https://www.genui.sh/docs/templates/markdown
- PDF Template: https://www.genui.sh/docs/templates/pdf
- Dynamic Template: https://www.genui.sh/docs/templates/dynamic