API

Most teams can manage Mosaicora from the panel. Use the API when you want another system to create sites, read templates, 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 create, update, and delete requests so retries stay safe.

Use page and pageSize for paginated list endpoints.

Expect the standard versioned error object when requests fail.

Queued cache flush and OG image generation requests return 202 Accepted.

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.

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"
}

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": "/"
}