curl -X POST http://localhost:3000/cma/v1/entries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "typeKey": "article",
    "slug": "hello-world",
    "fields": {
      "title": "Hello World",
      "body": "Welcome to HTMLess.",
      "author": "admin"
    }
  }'

{
  "id": "cln1a2b3c4d5e6f7g8h9i0j",
  "typeKey": "article",
  "slug": "hello-world",
  "state": "draft",
  "fields": {
    "title": "Hello World",
    "body": "Welcome to HTMLess.",
    "author": "admin"
  },
  "version": 1,
  "createdAt": "2026-04-03T12:00:00.000Z",
  "updatedAt": "2026-04-03T12:00:00.000Z"
}

curl -s http://localhost:3000/cda/v1/content/article?limit=10&sort=-createdAt&fields=title,slug,createdAt \
  -H "X-Space-Id: YOUR_SPACE_ID"

{
  "items": [
    {
      "id": "cln1a2b3c...",
      "slug": "hello-world",
      "fields": {
        "title": "Hello World",
        "slug": "hello-world",
        "createdAt": "2026-04-03T12:00:00.000Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

curl -s http://localhost:3000/preview/v1/content/article?slug=hello-world \
  -H "Authorization: Bearer PREVIEW_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

# Only return title and slug fields, expand the author reference
GET /cda/v1/content/article?fields=title,slug&include=author

# Sort by creation date descending, page 2 with 25 items
GET /cda/v1/content/article?sort=-createdAt&page=2&limit=25

curl -X POST http://localhost:3000/cma/v1/entries/ENTRY_ID:saveDraft \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "If-Match: \"v3\"" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"title":"Updated Title"}}'

# Returns 412 Precondition Failed if the ETag doesn't match

curl -X POST http://localhost:3000/cma/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@htmless.com",
    "password": "admin123"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_abc123",
    "email": "admin@htmless.com",
    "name": "Admin",
    "role": "admin"
  }
}

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

curl -X POST http://localhost:3000/cma/v1/api-tokens \
  -H "Authorization: Bearer ADMIN_JWT" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Next.js Frontend",
    "scopes": ["cda:read"],
    "expiresIn": "90d"
  }'

{
  "id": "tok_a1b2c3d4",
  "name": "Next.js Frontend",
  "token": "htk_live_xxxxxxxxxxxxxxxxxxxx",
  "scopes": ["cda:read"],
  "expiresAt": "2026-07-02T00:00:00.000Z"
}

curl -X POST http://localhost:3000/cma/v1/preview-tokens \
  -H "Authorization: Bearer ADMIN_JWT" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "preview.mysite.com",
    "entryId": "cln1a2b3c4d5e6f7g8h9i0j",
    "expiresIn": "1h"
  }'

curl -X POST http://localhost:3000/cma/v1/schemas/types \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "article",
    "name": "Article",
    "description": "Blog posts and articles"
  }'

curl -X POST http://localhost:3000/cma/v1/schemas/types/article/fields \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "title",
    "name": "Title",
    "type": "text",
    "required": true,
    "localized": true,
    "validations": {
      "minLength": 1,
      "maxLength": 200
    }
  }'

curl -X POST http://localhost:3000/cma/v1/taxonomies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "category",
    "hierarchical": true,
    "allowedTypes": ["article", "page"],
    "labels": {
      "singular": "Category",
      "plural": "Categories"
    }
  }'

// When a field is localized, its value is an object keyed by locale
{
  "fields": {
    "title": {
      "en": "Hello World",
      "fr": "Bonjour le monde",
      "de": "Hallo Welt"
    },
    "author": "admin"  // not localized, single value
  }
}

curl http://localhost:3000/cda/v1/content/article?slug=hello-world&locale=fr \
  -H "X-Space-Id: YOUR_SPACE_ID"

curl -X POST http://localhost:3000/cma/v1/schemas/types/article/publish \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

curl -X POST http://localhost:3000/cma/v1/entries/ENTRY_ID:saveDraft \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "title": "Updated Draft Title",
      "body": "Work in progress..."
    }
  }'

curl -X POST http://localhost:3000/cma/v1/entries/ENTRY_ID:publish \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

curl http://localhost:3000/cma/v1/entries/ENTRY_ID/versions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

{
  "items": [
    { "version": 3, "createdAt": "2026-04-03T14:30:00Z", "createdBy": "admin" },
    { "version": 2, "createdAt": "2026-04-03T13:00:00Z", "createdBy": "admin" },
    { "version": 1, "createdAt": "2026-04-03T12:00:00Z", "createdBy": "admin" }
  ]
}

curl -X POST http://localhost:3000/cma/v1/entries/ENTRY_ID:revert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"toVersion": 1}'

curl -X POST http://localhost:3000/cma/v1/entries/ENTRY_ID:schedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"publishAt": "2026-04-10T09:00:00Z"}'

// app/api/preview/route.ts
import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const slug = searchParams.get('slug');
  const previewToken = searchParams.get('token');

  // Validate the preview token with HTMLess
  const res = await fetch(
    `http://localhost:3000/preview/v1/content/article?slug=${slug}`,
    { headers: {
      'Authorization': `Bearer ${previewToken}`,
      'X-Space-Id': process.env.HTMLESS_SPACE_ID!,
    }}
  );

  if (!res.ok) return new Response('Invalid preview', { status: 401 });

  (await draftMode()).enable();
  redirect(`/articles/${slug}`);
}

{
  "typeKey": "heading",
  "version": "1.0.0",
  "attrs": {
    "level": 2,
    "text": "Getting Started with HTMLess"
  },
  "children": []
}

curl -X POST http://localhost:3000/cma/v1/blocks/definitions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "testimonial",
    "title": "Testimonial",
    "icon": "quote",
    "version": "1.0.0",
    "attributesSchema": {
      "type": "object",
      "properties": {
        "quote": { "type": "string" },
        "author": { "type": "string" },
        "role": { "type": "string" },
        "avatarAssetId": { "type": "string" }
      },
      "required": ["quote", "author"]
    }
  }'

curl -X POST http://localhost:3000/cma/v1/patterns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Article Intro",
    "blockTree": [
      { "typeKey": "heading", "attrs": { "level": 1, "text": "" } },
      { "typeKey": "paragraph", "attrs": { "text": "" } },
      { "typeKey": "image", "attrs": { "assetId": "", "alt": "" } }
    ]
  }'

import type { BlockInstance, BlockRendererMap } from '@htmless/core/blocks/renderer-sdk';
import { renderBlocks } from '@htmless/core/blocks/renderer-sdk';

const renderers: BlockRendererMap = {
  paragraph: ({ attrs }) => <p>{attrs.text}</p>,
  heading: ({ attrs }) => {
    const Tag = `h${attrs.level}` as keyof JSX.IntrinsicElements;
    return <Tag>{attrs.text}</Tag>;
  },
  image: ({ attrs }) => (
    <figure>
      <img src={attrs.url} alt={attrs.alt || ''} />
      {attrs.caption && <figcaption>{attrs.caption}</figcaption>}
    </figure>
  ),
  callout: ({ attrs }) => (
    <aside className={`callout callout-${attrs.tone}`}>
      {attrs.title && <strong>{attrs.title}</strong>}
      <p>{attrs.body}</p>
    </aside>
  ),
  code: ({ attrs }) => (
    <pre><code className={`language-${attrs.language}`}>
      {attrs.code}
    </code></pre>
  ),
};

function ArticleBody({ blocks }: { blocks: BlockInstance[] }) {
  return <>{renderBlocks(blocks, renderers)}</>;
}

import { extractText, collectAssetIds } from '@htmless/core/blocks/renderer-sdk';

// Extract all plain text for search indexing
const searchText = extractText(blocks);

// Collect asset IDs for preloading
const assetIds = collectAssetIds(blocks);

curl -X POST http://localhost:3000/cma/v1/assets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -F "file=@./photo.jpg" \
  -F "alt=A scenic mountain view" \
  -F "caption=Photo by John Doe"

{
  "id": "ast_k7m2n8p4",
  "filename": "photo.jpg",
  "mimeType": "image/jpeg",
  "bytes": 245891,
  "width": 1920,
  "height": 1080,
  "alt": "A scenic mountain view",
  "caption": "Photo by John Doe",
  "storageKey": "spaces/sp_abc/assets/ast_k7m2n8p4/photo.jpg",
  "createdAt": "2026-04-03T12:00:00.000Z"
}

https://assets.htmle.ss/{assetId}/{filename}?w=800&h=450&fit=crop&fm=webp&q=75

curl -X PATCH http://localhost:3000/cma/v1/assets/ast_k7m2n8p4 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"alt": "Updated alt text", "caption": "New caption"}'

curl http://localhost:3000/cma/v1/assets/ast_k7m2n8p4/usages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

# Response: { "usages": [ { "entryId": "...", "field": "heroImage" } ] }

curl -X POST http://localhost:3000/cma/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/api/webhooks/htmless",
    "events": ["entry.published", "entry.unpublished", "asset.created"],
    "active": true
  }'

{
  "id": "wh_a1b2c3d4",
  "url": "https://myapp.com/api/webhooks/htmless",
  "events": ["entry.published", "entry.unpublished", "asset.created"],
  "active": true,
  "signingSecret": "whsec_xxxxxxxxxxxxxxxx"
}

import { createHmac } from 'crypto';

function verifySignature(body: string, timestamp: string, signature: string, secret: string): boolean {
  // Reject if timestamp is older than 5 minutes (replay protection)
  const age = Date.now() - new Date(timestamp).getTime();
  if (age > 5 * 60 * 1000) return false;

  const message = `${timestamp}.${body}`;
  const expected = `sha256=${createHmac('sha256', secret).update(message).digest('hex')}`;

  return signature === expected;
}

// In your Express handler:
app.post('/api/webhooks/htmless', (req, res) => {
  const isValid = verifySignature(
    JSON.stringify(req.body),
    req.headers['x-htmless-timestamp'],
    req.headers['x-htmless-signature'],
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  // Process the event...
  console.log('Event:', req.body.eventType, req.body.data);
  res.sendStatus(200);
});

curl http://localhost:3000/cma/v1/webhooks/wh_a1b2c3d4/deliveries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Space-Id: YOUR_SPACE_ID"

curl -X POST http://localhost:3000/graphql \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ articles(limit: 10, sort: \"-createdAt\") { id slug fields { title createdAt } } }"
  }'

{
  "data": {
    "articles": [
      {
        "id": "cln1a2b3c...",
        "slug": "hello-world",
        "fields": {
          "title": "Hello World",
          "createdAt": "2026-04-03T12:00:00Z"
        }
      }
    ]
  }
}

curl -X POST http://localhost:3000/graphql \
  -H "X-Space-Id: YOUR_SPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ articles(slug: $slug) { id fields { title body } } }",
    "variables": { "slug": "hello-world" }
  }'

curl http://localhost:3000/graphql/schema \
  -H "X-Space-Id: YOUR_SPACE_ID"

{
  "schema": {
    "types": {
      "article": {
        "fields": {
          "title": { "type": "text", "required": true },
          "body": { "type": "richtext", "required": false },
          "heroImage": { "type": "media", "required": false }
        }
      }
    }
  }
}

async function fetchArticles() {
  const res = await fetch('http://localhost:3000/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Space-Id': 'YOUR_SPACE_ID',
    },
    body: JSON.stringify({
      query: `{
        articles(limit: 10, sort: "-createdAt") {
          id
          slug
          fields { title body createdAt }
        }
      }`,
    }),
  });

  const { data } = await res.json();
  return data.articles;
}

npm install @htmless/core
# or
pnpm add @htmless/core

import { HTMLessClient } from '@htmless/core/sdk/client';

const client = new HTMLessClient({
  baseUrl: 'http://localhost:3000',
  spaceId: 'YOUR_SPACE_ID',
  apiToken: 'htk_live_xxxxxxxxxxxxxxxxxxxx',
});

// List entries with filtering and sorting
const { items, meta } = await client.getEntries<Article>('article', {
  sort: '-createdAt',
  limit: 10,
  fields: ['title', 'slug', 'createdAt'],
  include: ['author'],
});

console.log(items);    // Article[]
console.log(meta.total); // total count

// Get a single entry by ID
const article = await client.getEntry<Article>('article', 'ENTRY_ID');

// Filter by slug
const { items: bySlug } = await client.getEntries<Article>('article', {
  slug: 'hello-world',
});

// List all content types
const types = await client.getTypes();

// Get a specific content type with its fields
const articleType = await client.getType('article');
console.log(articleType.fields); // ContentTypeField[]

const asset = await client.getAsset('ast_k7m2n8p4');
console.log(asset.filename);  // "photo.jpg"
console.log(asset.width);     // 1920
console.log(asset.mimeType);  // "image/jpeg"

// Fetch draft content for preview
const draft = await client.getPreview<Article>(
  'article',
  'hello-world',
  'PREVIEW_TOKEN'
);

import { HTMLessError } from '@htmless/core/sdk/client';

try {
  const article = await client.getEntry('article', 'nonexistent');
} catch (err) {
  if (err instanceof HTMLessError) {
    console.log(err.status); // 404
    console.log(err.body);   // raw error body
  }
}

import { HTMLessClient } from '@htmless/core/sdk/client';

const cms = new HTMLessClient({
  baseUrl: process.env.HTMLESS_URL!,
  spaceId: process.env.HTMLESS_SPACE_ID!,
  apiToken: process.env.HTMLESS_API_TOKEN!,
});

export default async function ArticlesPage() {
  const { items } = await cms.getEntries('article', {
    sort: '-createdAt',
    limit: 20,
  });

  return (
    <ul>
      {items.map((a: any) => (
        <li key={a.id}>
          <a href={`/articles/${a.slug}`}>{a.fields.title}</a>
        </li>
      ))}
    </ul>
  );
}

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: htmless
      POSTGRES_PASSWORD: ${DB_PASSWORD:-htmless_prod}
      POSTGRES_DB: htmless
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  api:
    build:
      context: .
      dockerfile: Dockerfile.api
    restart: unless-stopped
    ports:
      - "${API_PORT:-3000}:3000"
    environment:
      DATABASE_URL: postgresql://htmless:${DB_PASSWORD}@postgres:5432/htmless
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      NODE_ENV: production

  worker:
    build:
      context: .
      dockerfile: Dockerfile.worker
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://htmless:${DB_PASSWORD}@postgres:5432/htmless
      REDIS_URL: redis://redis:6379

  admin:
    build:
      context: .
      dockerfile: Dockerfile.admin
    restart: unless-stopped
    ports:
      - "${ADMIN_PORT:-3001}:3001"

volumes:
  pgdata:
  redisdata:

DB_PASSWORD=a-strong-random-password-here
JWT_SECRET=another-strong-random-secret-here
API_PORT=3000
ADMIN_PORT=3001

server {
    listen 443 ssl http2;
    server_name cms.example.com;

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

services:
  api:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.htmless-api.rule=Host(`api.cms.example.com`)"
      - "traefik.http.routers.htmless-api.tls.certresolver=le"
      - "traefik.http.services.htmless-api.loadbalancer.server.port=3000"

npm install -g @htmless/core
# or use npx
npx @htmless/core help

htmless init

# Creates:
#   docker-compose.yml
#   .env.example
#   htmless.config.ts

# Run all pending migrations
htmless migrate

# The command uses Prisma migrate deploy under the hood
# Make sure DATABASE_URL is set in your environment

htmless seed

# Output:
#   Created default space
#   Created admin user (admin@htmless.com / admin123)
#   Created roles: admin, editor, author, viewer
#   Seeded 7 core block definitions

htmless dev

# Starts:
#   API server on http://localhost:3000 (with file watching)
#   Admin UI on http://localhost:3001 (Next.js dev)

htmless codegen

# Generates: ./htmless.types.ts
# Example output:
# export interface Article {
#   title: string;
#   body: string;
#   author?: string;
#   heroImage?: string;
# }

import type { Article } from './htmless.types';
import { HTMLessClient } from '@htmless/core/sdk/client';

const { items } = await client.getEntries<Article>('article');
// items is typed as Article[]