Using the Content API

The content API lets merchants manage arbitrary structured data that your theme renders. The merchant defines the model schema and entries in the admin. Your theme fetches by slug.

Fetching a collection

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

Query params: page (default: 1), limit (default: 20, max: 50)

Response:

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

Each entry's fields are flattened directly onto the object alongside _id and updatedAt. The exact fields depend on the model schema the merchant defined.

Fetching a singleton

Same endpoint — the API detects the model type automatically.

Response:

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

data is null if no published entry exists. Always guard against this:

const { data } = await fetchContent('hero-banner');
if (!data) return null; // render default or nothing

Fetching a single entry

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

Response:

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

Only published entries

The API never returns draft or archived entries. If the merchant has not published any entry for a model, data will be empty or null.

Documenting your theme's content requirements

Your theme depends on specific model slugs and field names. Document them so merchants know what to create. Example:

Model slug	Type	Required fields
hero-banner	Singleton	headline (text), image (image), ctaText (text), ctaUrl (text)
faqs	Collection	question (text), answer (rich text)
announcement	Singleton	message (text), active (boolean)

If a required model doesn't exist, the API returns CONTENT_MODEL_NOT_FOUND (404). Handle this gracefully — most content sections should fail silently rather than crashing the page.

Possible errors

Code	HTTP	Cause
CONTENT_MODEL_NOT_FOUND	404	Model slug doesn't exist in the admin
CONTENT_ENTRY_NOT_FOUND	404	Entry ID not found or entry is not published