Skip to main content

Content Models

Content models let merchants define arbitrary structured data that your theme fetches and renders. Think of it as a lightweight Directus built into the admin — the merchant controls the schema and entries, your theme consumes them.

Common use cases​

  • Hero banner (singleton)
  • Store announcement or notice (singleton)
  • FAQ entries (collection)
  • Team members (collection)
  • Promotional banners (collection)
  • Custom landing page sections (collection)

Model types​

Singleton​

A model with one active record. Fetching a singleton returns the record directly with all fields flattened onto the response:

{
  "status": "success",
  "data": {
    "_id": "69e79abd788c032f28310446",
    "updatedAt": "2024-06-01T00:00:00Z",
    "headline": "Summer Sale",
    "image": "https://..."
  }
}

If no published entry exists, data is null. Your theme must handle this case:

if (!data) {
  return null; // render nothing or a default
}

Collection​

A model with multiple records, returned paginated. Each entry has its fields flattened directly onto it:

{
  "status": "success",
  "data": {
    "currentPage": 1,
    "totalPages": 2,
    "totalDocuments": 8,
    "limit": 20,
    "data": [
      {
        "_id": "...",
        "updatedAt": "2024-06-01T00:00:00Z",
        "question": "What is your return policy?",
        "answer": "30 days, no questions asked."
      }
    ]
  }
}

Published entries only​

The API only returns entries with status published. Drafts and archived entries are never included. If data appears to be missing, check that the entry is published in the admin.

Accessing content​

Content models are accessed by their slug — a short identifier the merchant sets when creating the model:

GET /access/api/v1/content/:modelSlug
GET /access/api/v1/content/:modelSlug/:entryId

Coordinating with merchants​

Your theme expects specific model slugs (e.g. hero-banner, faqs). Document the slugs your theme requires so merchants know what to create in the admin. If a model slug doesn't exist the API returns CONTENT_MODEL_NOT_FOUND (404).

See the full Content API guide for fetch examples.