API

Most teams can manage Mosaicora from the panel. Use the API when another system needs to create sites, read templates, generate image bytes, or trigger operations automatically.

A developer will need an API token from the panel. A token is a private key for API access, so copy it once, store it securely, and send it with each request.

Access and request patterns

Use your Mosaicora API base URL for requests. Your workspace or onboarding materials should provide the correct production endpoint.

Send Authorization: Bearer <token> on every authenticated request.

Use Idempotency-Key for image generation and every create, update, or delete request so retries stay safe.

Use page and pageSize for paginated list endpoints.

Expect the standard versioned error object when requests fail.

Synchronous saved-template generation returns image bytes with 200 OK. Queued site generation and cache flush operations return 202 Accepted.

Image generation accepts a request body of up to 1 MB and supports JPEG, PNG, and WebP output.

Generation respects the API rate limit and the current Open Graph image allowance for the account.

Synchronous image generation

Generate an Open Graph image directly from a saved template and receive the image bytes in the response.

• •

  Send type: "og" and a saved templateId. The optional format accepts jpg, jpeg, png, or webp and defaults to JPEG.

• •

  The content object and every template field are optional. Only values supplied in the request render, so omitted fields do not use saved content or base-template examples.

• •

  The optional design object applies supported canonical design values over the saved template. Supplied nested values take priority while omitted values keep the saved design.

• •

  Renderer transport fields, dimensions, quality, and logo configuration are not available as design overrides.

• •

  This endpoint does not resolve site brands. A template with a custom logo URL keeps that logo, while a template configured to use a saved brand logo renders without the logo.

• •

  A successful response returns binary image bytes with X-Request-Id, X-Image-Type, X-Image-Format, and X-Template-Id headers.

Account

Confirm the authenticated identity associated with the API token.

• •

  GET /api/v1/me - Return the authenticated user and token identifiers.

Sites

Create, inspect, update, and delete Mosaicora sites and their settings.

• •

  GET /api/v1/sites - List sites with pagination.

• •

  POST /api/v1/sites - Create a site.

• •

  GET /api/v1/sites/{site_id} - Read a site by id.

• •

  PATCH /api/v1/sites/{site_id} - Update a site.

• •

  DELETE /api/v1/sites/{site_id} - Delete a site.

Page type rules

Manage page type rules for a site, including URL rules, scraped-type rules, and broader non-home rules.

• •

  GET /api/v1/sites/{site_id}/page-type-rules - List page type rules for a site.

• •

  POST /api/v1/sites/{site_id}/page-type-rules - Create a page type rule.

• •

  GET /api/v1/sites/{site_id}/page-type-rules/{rule_id} - Read a page type rule by id.

• •

  PATCH /api/v1/sites/{site_id}/page-type-rules/{rule_id} - Update a page type rule.

• •

  DELETE /api/v1/sites/{site_id}/page-type-rules/{rule_id} - Delete a page type rule.

Brands

Manage brand records and set a default brand for the account.

• •

  GET /api/v1/brands - List brands with pagination.

• •

  POST /api/v1/brands - Create a brand.

• •

  GET /api/v1/brands/{brand_id} - Read a brand by id.

• •

  PATCH /api/v1/brands/{brand_id} - Update a brand.

• •

  DELETE /api/v1/brands/{brand_id} - Delete a brand.

• •

  POST /api/v1/brands/{brand_id}/default - Set a brand as the default brand.

Templates

Browse the available templates and inspect a specific template by id.

• •

  GET /api/v1/templates - List templates with pagination.

• •

  GET /api/v1/templates/{template_id} - Read a template by id.

• •

  GET /api/v1/templates/{template_id}/fields - Read the ordered content fields accepted by a saved template.

Images

Generate image bytes synchronously from a saved template and optional request values.

• •

  POST /api/v1/images/generate - Generate a JPEG, PNG, or WebP Open Graph image and return the binary response.

Operations

Trigger asynchronous site operations that return accepted responses.

• •

  POST /api/v1/sites/{site_id}/cache/flush - Flush the cached output for a site path.

• •

  POST /api/v1/sites/{site_id}/og-images/generate - Queue OG image generation for a site path.

Authenticate with GET /me

Confirm that the token is valid before building a larger integration.

curl https://api.mosaicora.io/api/v1/me \
  -H "Authorization: Bearer mos_your_token"

{
  "userId": "usr_123",
  "tokenId": "tok_123"
}

List sites

List sites with page and page-size controls.

curl "https://api.mosaicora.io/api/v1/sites?page=1&pageSize=25" \
  -H "Authorization: Bearer mos_your_token"

{
  "page": 1,
  "pageSize": 25,
  "rows": [],
  "total": 0,
  "totalPages": 1
}

Create a site

Use Idempotency-Key when creating a site so a retry does not create duplicates.

curl -X POST https://api.mosaicora.io/api/v1/sites \
  -H "Authorization: Bearer mos_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-example-com-001" \
  -d '{"name":"Example","url":"https://example.com"}'

{
  "id": "site_123",
  "name": "Example",
  "url": "https://example.com"
}

Inspect template fields

Inspect the ordered fields accepted by a saved template before building the generation request.

curl https://api.mosaicora.io/api/v1/templates/template_123/fields \
  -H "Authorization: Bearer mos_your_token"

{
  "templateId": "template_123",
  "baseTemplateId": "saas-1",
  "defaultFormat": "jpeg",
  "acceptedFormats": ["jpg", "jpeg", "png", "webp"],
  "fields": [
    {
      "key": "title",
      "valueType": "text",
      "semanticRole": "content.title",
      "autoMap": true
    }
  ]
}

Generate an Open Graph image

Generate an image synchronously from a saved template and write the binary response to a file.

curl -X POST https://api.mosaicora.io/api/v1/images/generate \
  -H "Authorization: Bearer mos_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-launch-png-001" \
  -d '{"type":"og","templateId":"template_123","format":"png","content":{"title":"Product launch"}}' \
  --output product-launch.png

HTTP 200 OK
Content-Type: image/png
X-Request-Id: req_123
X-Image-Type: og
X-Image-Format: png
X-Template-Id: template_123

The binary image bytes are written to product-launch.png.

Queue operations

Queued operations return accepted responses while Mosaicora completes the work in the background.

# Queue OG image generation
curl -X POST https://api.mosaicora.io/api/v1/sites/site_123/og-images/generate \
  -H "Authorization: Bearer mos_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: og-site_123-home-001" \
  -d '{"path":"/"}'

# Flush cache for a site path
curl -X POST https://api.mosaicora.io/api/v1/sites/site_123/cache/flush \
  -H "Authorization: Bearer mos_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: flush-site_123-home-001" \
  -d '{"path":"/"}'

{
  "queued": true,
  "siteId": "site_123",
  "path": "/"
}