Content API reference

Every tenant is one document in the sites collection. Its key field (the siteKey) identifies the tenant; consumer apps authenticate with the site's API key, which resolves to this document.

All other content documents carry a siteId field referencing the owning sites document. companies and siteSettings are one-per-site; legalTexts is one-per-document-key; services, products, projects, posts, testimonials, faqs, locations and values are one-per-slug within a site; blocks are one-per-key within a site; assets are one-per-pathname.

All documents also carry MongoDB _id, createdAt and updatedAt fields managed by the database layer; they are omitted from the tables below.

The platform owns design-agnostic business data only: business identity and contacts, opening hours, the services performed, the products sold, the projects published, the posts written, the testimonials received, the questions answered, locations, company values, and the legal documents the client maintains. Every client website has its own bespoke design, so page structure, layout, section copy and metadata (band headings, stat figures, call-to-action labels, intro blocks) live in the client site's own repository and are deliberately absent from this contract.

Website blocks are the one opening in that rule, and it is the site's to make. A site may declare some of its own copy as blocks — named groups of typed fields (text, richText, number, image, link, list, collection) — in a manifest it syncs with PUT /api/v1/blocks/definitions. The platform then stores one blocks document per declared block, the owner edits its values in the backoffice, and the site reads them from GET /api/v1/blocks. The platform stores the fields and their values only, never the site's markup or styles; which blocks exist, and on which page, is decided by the site's manifest, not in the backoffice.

Each resource maps to one collection: settings to companies, services/products/projects/testimonials/faqs/locations/values to their per-slug collections (array position stored in each document's order field), posts to the posts collection (ordered by the publishedAt date each post carries rather than by a sort index), legal to one legalTexts document per document key, and blocks to one blocks document per declared block key (in the manifest's order, hidden blocks left out). Platform-only data never leaves: companies.availability is the schedule designer's working data (client sites read the schedule lines derived from it), posts.status decides whether a post is served at all rather than being served alongside it, and the whole siteSettings document holds backoffice preferences.

A service is work scoped per job and carries no price; a product is something sold at a stated price, stored as an amount plus its currency and billing period so each website can format it in its own style; a project is work already delivered, told as problem, solution and results; a post is something the business wrote, dated and published on its own decision; a testimonial is what somebody else said about the business, optionally rated and attributed; an FAQ is one question and its answer, grouped under a heading the tenant chose.

Resource responses omit siteId and every platform-only field, and they are fully defaulted: missing strings come back as empty strings and missing arrays as empty arrays. A site with no content yet returns valid empty resources rather than an error, so client sites can render an empty state. Block values are the exception: a block field with no value is absent from its block's values, so the site renders its own fallback copy.

Two kinds of field are markup rather than text: a post's body and a block's richText fields are HTML fragments. Each is sanitised against its own fixed element allowlist when the tenant saves it, so what the collection stores is already what may be rendered, and a consumer inserts it as HTML rather than escaping it. Every other text field on this contract is plain.

Two collections are served with a document withheld rather than flagged, so a consumer never has a state to check: an unpublished post, and a testimonial created but not yet written. Everything else in a collection is served as stored.

Content can be multilingual. A site has a main content language (sites.defaultContentLocale) and any number of extra ones (sites.contentLocales), from a fixed list. Main-language text lives in each document's ordinary fields; every other language lives beside it in translations.<locale>, holding only that type's translatable fields. Everything else — slugs, prices, URLs, dates, icons, addresses, the names of people and clients — is language-neutral and stored once. The Site API resolves a language at read time: each resource takes ?locale=, a field with no translation falls back to the main language and is named in the item's untranslated list, and the opening-hours lines are derived from availability in the language asked for. A legal document is served translated whole or not at all. Removing a language from a site hides it from the API and deletes nothing. The translations field itself is never served: a client site receives one language per response, in the resource's ordinary shape.

Every uploaded file lives in the assets collection, stored in Vercel Blob through the backoffice. The pathname is the storage key and stays internal: the Site API delivers each file as an absolute url on the store's CDN, which a client site uses directly. A service, a product, a testimonial or a post's cover embeds the pathname of its single image; a project references whole asset documents, so its files arrive with their kind, MIME type, name, size and pixel dimensions resolved. A post does both: the images inside its body carry their URLs in the markup, and the document lists the asset ids behind them so an image still in use is never retired.