Docs

Site API reference

Version 6.3.0 · Markdown version at /api/v1/docs

casadigital.pt is the single owner of all customer data. Client websites — and any other app built on this platform — never touch the database directly: they read and write through this HTTP API.

Every tenant (a Site) has its own API key, issued when the site is provisioned. The key both authenticates the request and identifies the tenant, so no site identifier needs to be sent.

Building a site on the platform?

This page documents the endpoints. The full integration contract — environment, caching, the invalidation endpoint a client site should expose, limits and error handling — is at /api/v1/integration.md, described as OpenAPI 3.1 at /api/v1/openapi.json and indexed for agents at /llms.txt.

/api/v1/integration.md— the full integration contract, as Markdown
/api/v1/openapi.json— OpenAPI 3.1 description of every endpoint
/api/content-schema— JSON Schema per content resource
/llms.txt— index for AI agents (/llms-full.txt for one fetch)

Authentication

All authenticated endpoints expect the key in the Authorization header: "Authorization: Bearer sk_<48 hex chars>".

Requests with a missing or unknown key receive 401. Keys are managed by Casa Digital; if a key leaks it can be regenerated, which immediately invalidates the old one.

Authorization: Bearer sk_0123abcd…

Content resources

Content is served one resource at a time so each consumer fetches only what it renders and caches it on its own schedule. There is no combined content document.

Every resource response is wrapped in the same envelope: { version, siteKey, <resource> }. Compare version against the contract version you built against and log loudly on a major mismatch.

An empty site is a valid site. Singleton resources come back fully defaulted (absent strings are empty strings) and collections come back as empty arrays, so a website whose content has not been authored yet still renders. Content problems are never signalled by a 404.

The platform serves design-agnostic business data only. Layout and section copy belong to each website's own design and are not part of these resources.

Endpoints

GET

/api/v1/settings

API key

Business name, tagline, description, contact details, opening schedule and social links for the authenticated site.

Response

200 with { version, siteKey, settings } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "settings": {
    "name": "…",
    "tagline": "…",
    "phone": "+351 912 345 678",
    "schedule": [{ "days": "Seg – Sáb", "hours": "09h – 19h" }],
    "social": { "instagram": "…", "facebook": "" }
  }
}

Field	Type	Required	Description
name	string	no	Business name as displayed across the site.
tagline	string	no	One-line slogan shown near the logo/footer. Portuguese.
description	string	no	Short description of the business, 1-2 sentences. Portuguese.
phone	string	no	Display phone number, formatted for reading (e.g. "+351 912 345 678"). Empty string if none. Derive a tel: URI from it by stripping everything but + and digits.
email	string	no	Public contact email. Empty string if none.
whatsapp	string	no	WhatsApp chat URL (e.g. "https://wa.me/351912345678"). Empty string if none.
appUrl	string	no	Mobile app store URL if the business has an app. Empty string if none.
schedule	array of object	no	Opening schedule rows, in display order.
schedule[].days	string	no	Day range label (e.g. "Seg – Sáb"). Portuguese.
schedule[].hours	string	no	Opening hours label (e.g. "09h – 19h" or "Fechado").
social	object	no	Social media profile links.
social.facebook	string	no	Facebook page URL. Empty string if none.
social.instagram	string	no	Instagram profile URL. Empty string if none.
social.linkedin	string	no	LinkedIn page URL. Empty string if none.
social.x	string	no	X/Twitter profile URL. Empty string if none.
social.youtube	string	no	YouTube channel URL. Empty string if none.

GET

/api/v1/services

API key

Services for the authenticated site in display order, each with a slug, title, icon key, display tier, copy and an optional image.

An image arrives as an absolute `url` served from the blob store's CDN — usable as an image source as it stands, provided your image optimiser allows the host.

Response

200 with { version, siteKey, services } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "services": [
    {
      "slug": "mudancas",
      "title": "Mudanças",
      "icon": "truck",
      "tier": "primary",
      "short": "…",
      "description": "…",
      "bullets": ["…"]
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].title	string	no	Service name. Portuguese.
[].icon	"truck" \| "wrench" \| "packageCheck" \| "hammer" \| "boxes" \| "warehouse" \| "arrowDownToLine" \| "zap" \| "clock" \| "shieldCheck"	yes	Icon key from the fixed icon set (Lucide-style names).
[].image	object	no	Illustrative image stored in Vercel Blob.
[].image.assetId	string	no	Asset document id, set by the backoffice after upload.
[].image.url	string	no	Absolute URL of the image, served from the blob store's CDN. Use it directly as an image source; no API key is involved. Allow the host in your image optimiser.
[].image.alt	string	no	Image alt text. Portuguese.
[].image.width	integer	no	Image width in pixels.
[].image.height	integer	no	Image height in pixels.
[].tier	"primary" \| "featured" \| "secondary"	yes	Display tier: "primary" for the main highlighted services, "featured" for the secondary highlights, "secondary" for the rest.
[].short	string	no	One-sentence summary shown on service cards. Portuguese.
[].description	string	no	Full description. Portuguese.
[].bullets	array of string	no	Bullet-point highlights. Portuguese.

GET

/api/v1/products

API key

Products for the authenticated site in display order, each with a slug, title, icon key, copy, an optional image and a price.

The price is an amount plus its currency and billing period, so each website formats it in its own style. A price of 0 means it is not published, and `available: false` marks a product kept on record but not currently sold.

Response

200 with { version, siteKey, products } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "products": [
    {
      "slug": "caixa-cartao-60x40",
      "title": "Caixa de cartão 60x40",
      "icon": "boxes",
      "sku": "CX-6040",
      "price": 2.5,
      "currency": "EUR",
      "pricePeriod": "once",
      "priceNote": "IVA incluído",
      "featured": false,
      "available": true
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].title	string	no	Product name. Portuguese.
[].icon	"truck" \| "wrench" \| "packageCheck" \| "hammer" \| "boxes" \| "warehouse" \| "arrowDownToLine" \| "zap" \| "clock" \| "shieldCheck"	yes	Icon key from the fixed icon set (Lucide-style names).
[].image	object	no	Illustrative image stored in Vercel Blob.
[].image.assetId	string	no	Asset document id, set by the backoffice after upload.
[].image.url	string	no	Absolute URL of the image, served from the blob store's CDN. Use it directly as an image source; no API key is involved. Allow the host in your image optimiser.
[].image.alt	string	no	Image alt text. Portuguese.
[].image.width	integer	no	Image width in pixels.
[].image.height	integer	no	Image height in pixels.
[].sku	string	no	Internal reference or article number. Empty string if none.
[].price	number	no	Price amount in the currency below. 0 means the price is not published.
[].currency	"EUR" \| "USD" \| "GBP"	no	Currency of the price amount.
[].pricePeriod	"once" \| "month" \| "year"	no	Billing period the price refers to: "once" for a one-off price, "month" or "year" for a subscription.
[].priceNote	string	no	Short qualifier shown next to the price (e.g. "IVA incluído"). Portuguese.
[].short	string	no	One-sentence summary shown on product cards. Portuguese.
[].description	string	no	Full description. Portuguese.
[].bullets	array of string	no	Bullet-point highlights. Portuguese.
[].featured	boolean	no	True for a product the website should highlight.
[].available	boolean	no	False for a product kept on record but not currently sold.

GET

/api/v1/projects

API key

Work the business has already delivered, in display order: the client it was for, then the problem, the solution and the results, plus related links.

Every attached file arrives in one `assets` array with its absolute `url`, `kind` (`image`, `video` or `document`), MIME type, original filename, byte size and, for media, its pixel dimensions. Group by `kind` if your design shows media separately from documents; the `url` is ready to use as a source or a download link.

Response

200 with { version, siteKey, projects } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "projects": [
    {
      "slug": "projeto-mudanca-armazem",
      "client": "Padaria Central",
      "problem": "…",
      "solution": "…",
      "results": "…",
      "links": [{ "title": "Website do cliente", "url": "https://exemplo.pt" }],
      "assets": [
        {
          "kind": "image",
          "url": "https://abc123xyz.public.blob.vercel-storage.com/sites/my-business/antes-abc123.webp",
          "contentType": "image/webp",
          "name": "antes.webp",
          "alt": "",
          "size": 184320,
          "width": 1600,
          "height": 1067
        },
        {
          "kind": "document",
          "url": "https://abc123xyz.public.blob.vercel-storage.com/sites/my-business/relatorio-def456.pdf",
          "contentType": "application/pdf",
          "name": "relatorio.pdf",
          "alt": "",
          "size": 240128
        }
      ]
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].title	string	no	Name of the project, as the website should title it. Read this as the heading; a project stored before 6.1.0 may carry only `client`, so fall back to that when this is empty.
[].client	string	no	Name of the client the work was delivered for. Empty when there is no client to name — the business's own product, or work it may not attribute.
[].problem	string	no	The situation the client was in. Portuguese.
[].solution	string	no	What the business did about it. Portuguese.
[].results	string	no	What the client got out of it. Portuguese.
[].links	array of object	no	Related links, in display order.
[].links[].title	string	no	Link label. Portuguese. May be empty — fall back to showing the URL.
[].links[].url	string	no	Absolute URL, including the scheme.
[].assets	array of object	no	Every attached file in one list, in display order. Group them by `kind` if your design shows media separately from documents.
[].assets[].kind	"image" \| "video" \| "document"	yes	What the file is, derived from its MIME type: "image" and "video" are media, everything else is a "document". Split a list on this rather than on the file extension.
[].assets[].url	string	yes	Absolute URL of the file, served from the blob store's CDN. Use it directly — as an image source, a video source, or the href of a download link — with no API key involved.
[].assets[].contentType	string	no	MIME type the file was stored with (e.g. "image/webp", "application/pdf").
[].assets[].name	string	no	Original filename at upload time. Use it as the download label for a document.
[].assets[].alt	string	no	Alt text, when one was written. Often empty — fall back to the surrounding context.
[].assets[].size	integer	no	File size in bytes, when known.
[].assets[].width	integer	no	Intrinsic width in pixels. Present for media, absent for documents.
[].assets[].height	integer	no	Intrinsic height in pixels. Present for media, absent for documents.

GET

/api/v1/posts

API key

News and articles the business writes itself, newest first by `publishedAt`. Only published posts are served: a draft is absent from this list entirely, so there is no state to check before rendering one.

`body` is an HTML fragment, unlike every other text on this API. It is sanitised when the tenant saves it, against a fixed allowlist — `p`, `h2`–`h4`, `strong`, `em`, `u`, `s`, `code`, `pre`, `blockquote`, `ul`, `ol`, `li`, `a`, `img`, `hr`, `br` — so that is the whole set of elements your stylesheet has to cover. Headings start at `h2`, because the `h1` of the page is the post's `title`.

An `img` in a body is always a file from this tenant's own blob store, with the same absolute `url` shape as every other file on this API. It carries `alt`, its pixel dimensions and `data-align` (`left`, `center` or `right`) — the writer's intent, for your design to interpret. There is no inline CSS and no class attribute.

`publishedAt` and `updatedOn` are calendar dates, not instants: format them in UTC or the day will read as the one before for anyone west of Greenwich.

Response

200 with { version, siteKey, posts } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "posts": [
    {
      "slug": "novo-armazem-em-leiria",
      "title": "Novo armazém em Leiria",
      "excerpt": "Duplicámos a capacidade de armazenamento na zona centro.",
      "body": "<p>A partir de <strong>setembro</strong> passamos a operar…</p><h2>O que muda para os clientes</h2><p>…</p><img src=\"https://abc123xyz.public.blob.vercel-storage.com/sites/my-business/armazem-abc123.webp\" alt=\"Interior do novo armazém\" width=\"1600\" height=\"1067\" data-align=\"center\" data-asset-id=\"6712f0a1b2c3d4e5f6a7b8c9\">",
      "coverImage": {
        "url": "https://abc123xyz.public.blob.vercel-storage.com/sites/my-business/capa-abc123.webp",
        "alt": "Fachada do novo armazém",
        "width": 1600,
        "height": 900
      },
      "publishedAt": "2026-08-24",
      "updatedOn": "",
      "tags": ["armazenamento", "leiria"],
      "author": "Ana Ferreira"
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].title	string	no	Headline of the post. Portuguese.
[].excerpt	string	no	Standfirst: one or two sentences summarising the post. Plain text, no markup — it is written for a card and for a meta description. Portuguese.
[].body	string	no	The post itself, as an HTML fragment (no <html> or <body> wrapper). Render it as HTML; it is sanitised on save against a fixed allowlist, so the only elements it can contain are p, h2, h3, h4, strong, em, u, s, code, pre, blockquote, ul, ol, li, a, img, hr, br. Headings start at h2, because the page's h1 is the title above. An <a> carries href, and one leaving the site also carries target and rel. An <img> is always a file from this tenant's own blob store and carries src, alt, width, height and data-align ("left", "center" or "right") — style the alignment yourself, there is no inline CSS. Empty string for a post with no body yet.
[].coverImage	object	no	Lead image for the post, shown on a card and at the top of the page.
[].coverImage.assetId	string	no	Asset document id, set by the backoffice after upload.
[].coverImage.url	string	no	Absolute URL of the image, served from the blob store's CDN. Use it directly as an image source; no API key is involved. Allow the host in your image optimiser.
[].coverImage.alt	string	no	Image alt text. Portuguese.
[].coverImage.width	integer	no	Image width in pixels.
[].coverImage.height	integer	no	Image height in pixels.
[].publishedAt	string	no	The day the post is dated, as "YYYY-MM-DD". Treat it as a calendar date, not an instant: format it in UTC or the day will read as the one before west of Greenwich. Posts arrive newest first.
[].updatedOn	string	no	The day the post was last revised, as "YYYY-MM-DD". Empty when it has not been revised since publishing — useful as dateModified in structured data.
[].tags	array of string	no	Free-text labels the business groups its posts by. Display order. Not a fixed vocabulary and not slugs — slugify them yourself if you route by them.
[].author	string	no	Who wrote it, as it should be credited. Empty when the business does not by-line its posts.

GET

/api/v1/testimonials

API key

What clients have said about the business, in display order. There is no draft state and nothing to filter: a testimonial the tenant no longer wants is deleted, and one created but not yet written is withheld, so everything here has words in it.

`rating` is a whole number of stars out of 5, and 0 means the testimonial came without one — show the words alone rather than an empty row of stars.

`author` may be empty (an anonymous testimonial) and `image`, the photograph of the person quoted, is usually absent. `date` is a calendar date: format it in UTC.

Response

200 with { version, siteKey, testimonials } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "testimonials": [
    {
      "slug": "padaria-central",
      "author": "Ana Ferreira",
      "role": "Gerente, Padaria Central",
      "quote": "Entregam sempre à hora combinada. Em dois anos nunca falhámos uma abertura.",
      "rating": 5,
      "date": "2026-06-12",
      "image": {
        "url": "https://abc123xyz.public.blob.vercel-storage.com/sites/my-business/ana-abc123.webp",
        "alt": "Ana Ferreira",
        "width": 400,
        "height": 400
      }
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].author	string	no	Who said it, as they should be credited. Empty for an anonymous testimonial.
[].role	string	no	Who the author is, in their own words (e.g. "Gerente, Padaria Central"). One line, meant to be read under the name. Portuguese.
[].quote	string	no	What they said. Plain text, no markup. Portuguese.
[].rating	integer	no	Stars out of 5. 0 means the testimonial came without a rating — show the words alone rather than zero stars.
[].date	string	no	The day it was given, as "YYYY-MM-DD". Empty when it is not dated. A calendar date, not an instant: format it in UTC.
[].image	object	no	Photograph of the author, when there is one. Often absent.
[].image.assetId	string	no	Asset document id, set by the backoffice after upload.
[].image.url	string	no	Absolute URL of the image, served from the blob store's CDN. Use it directly as an image source; no API key is involved. Allow the host in your image optimiser.
[].image.alt	string	no	Image alt text. Portuguese.
[].image.width	integer	no	Image width in pixels.
[].image.height	integer	no	Image height in pixels.

GET

/api/v1/faqs

API key

The questions the business answers before they are asked, in display order, with the questions of a group together.

`category` is the tenant's own heading for a group and is free text, not a vocabulary: group on the exact string, and expect an ungrouped question (an empty `category`) beside grouped ones.

`answer` is plain text — split it on its line breaks to lay out paragraphs, as with a legal section's body. `slug` is stable, so it works as the anchor of a question you can link to.

Response

200 with { version, siteKey, faqs } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "faqs": [
    {
      "slug": "fazem-entregas-ao-sabado",
      "question": "Fazem entregas ao sábado?",
      "answer": "Sim, entre as 9h e as 13h na área metropolitana de Lisboa.\n\nFora dessa área, apenas em dias úteis.",
      "category": "Entregas"
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated. Stable, so it works as the anchor of a linkable question.
[].question	string	no	The question, as a client would ask it. Portuguese.
[].answer	string	no	The answer. Plain text, no markup; split it on its line breaks to lay out paragraphs, like a legal section's body. Portuguese.
[].category	string	no	Free-text heading this question is grouped under (e.g. "Entregas"). Empty for an ungrouped question. Not a fixed vocabulary and not a slug — group by the exact string, and expect an empty one alongside filled ones.

GET

/api/v1/locations

API key

Locations for the authenticated site in display order, with address lines and optional Google Maps URLs. At most one is flagged primary.

Response

200 with { version, siteKey, locations } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "locations": [
    {
      "slug": "lisboa",
      "city": "Lisboa",
      "lines": ["Rua Exemplo 12", "1000-001 Lisboa"],
      "primary": true
    }
  ]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].city	string	no	City or locality name.
[].lines	array of string	no	Address lines, in display order.
[].mapsSearchUrl	string	no	Google Maps search/share URL for this address. Empty string if none.
[].mapEmbedUrl	string	no	Google Maps embed URL (iframe src). Empty string if none.
[].primary	boolean	no	True for the main location (at most one per site).

GET

/api/v1/values

API key

Company values for the authenticated site in display order.

Response

200 with { version, siteKey, values } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "values": [{ "slug": "qualidade", "title": "Qualidade", "description": "…" }]
}

Field	Type	Required	Description
[].slug	string	yes	URL-safe unique identifier, lowercase, hyphen-separated.
[].title	string	no	Value name (e.g. Qualidade). Portuguese.
[].description	string	no	Short explanation of the value. Portuguese.

GET

/api/v1/legal

API key

Terms and privacy text the client maintains in the backoffice, keyed by document, each an ordered list of title and body sections.

This is the only page-shaped content the platform holds. Which pages a website has, what they say and how they are titled belongs to the website itself.

Response

200 with { version, siteKey, legal } — empty content included. 401 on bad key.

{
  "version": "6.3.0",
  "siteKey": "my-business",
  "legal": {
    "terms": { "sections": [{ "title": "1. Objeto", "body": "…" }] },
    "privacy": { "sections": [{ "title": "1. Dados recolhidos", "body": "…" }] }
  }
}

Field	Type	Required	Description
<key>	object	no	One legal document.
<key>.sections	array of object	no	Ordered sections, as the document should read.
<key>.sections[].title	string	no	Section heading. Portuguese.
<key>.sections[].body	string	no	Section body prose; plain text, may contain multiple sentences. Portuguese.

POST

/api/v1/leads

API key

Creates a lead for the authenticated site — typically a quote or contact form submission. The lead enters the backoffice CRM pipeline with status "new".

If the tenant enabled SMS or Telegram notifications in the backoffice, they are notified. Unless they turned it off, the platform also emails the person who filled the form to confirm it arrived — so your site should not send a confirmation of its own. Notification failures never fail the request.

Request body

Field	Type	Required	Description
name	string	yes	Contact name. Required.
email	string (email)	yes	Contact email. Required.
phone	string	no	Contact phone, free format.
formType	"quote" \| "contact"	no	Which website form produced the lead. Defaults to "quote" for older client sites that do not send it.
serviceSlug	string	no	Slug of the service the visitor is interested in.
originDestination	string	no	Pickup / delivery description, for transport-style quote forms.
message	string	yes	The visitor's message. Required.

Response

201 with { success: true, id }. 422 with field issues when the payload is invalid. 401 on bad key.

{
  "success": true,
  "id": "665f1c2ab8d3e0a1f0c4d5e6"
}

Content formats

The shape of each resource is documented separately: JSON Schema at /api/content-schema, human-readable reference at /docs/content-api, Markdown for AI agents at /api/content-schema/docs. Open the content format reference.