Schemas

The named shapes the REST API's fields link to: every entity and model, documented once instead of repeated at every use.

66 schemasEnglish only

AccountDataExport

Everything Mercastra stores about the account and the workshops it belongs to, for portability. Workshops the account is only a member of (not the owner) are included in the same list as owned ones.

Field	Type	Required	Constraints	Description
user	AccountDataExportUser	Yes	-	The account record as stored, minus authentication method secrets.
workshops	array of AccountDataExportWorkshopEntry	Yes	-	-
feedback	array of AccountDataExportFeedback	Yes	-	-
authProviders	array of AccountDataExportAuthProvider	Yes	-	-

AccountDataExportAuthProvider

A linked OAuth provider identity, as stored.

Field	Type	Required	Constraints	Description
provider	string	Yes	`const: "google"`	-
subject	string	Yes	-	-
linkedAt	string	Yes	`format: "date-time"`	-

AccountDataExportEstimate

An estimate belonging to the workshop, with its saved revisions. Its PDF exports and hand-offs are not included (tracked in MR-44).

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
name	string	Yes	-	-
recipientName	string	No	-	-
createdAt	string	Yes	`format: "date-time"`	-
updatedAt	string	Yes	`format: "date-time"`	-
markupPercent	number	Yes	-	-
discountPercent	number	Yes	-	-
lineItems	array of AccountDataExportLineItem	Yes	-	-
revisions	array of AccountDataExportEstimateRevision	Yes	-	-

AccountDataExportEstimateRevision

A saved revision of an estimate, as stored.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
revisionNumber	number	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-
createdByUid	string	Yes	-	-
name	string	Yes	-	-
markupPercent	number	Yes	-	-
discountPercent	number	Yes	-	-
lineItems	array of AccountDataExportLineItem	Yes	-	-

AccountDataExportFeedback

One feedback or support message the account submitted.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
kind	FeedbackKind	Yes	-	Whether the message is general feedback or a support request.
title	string	Yes	-	-
message	string	Yes	-	-
email	string	Yes	`format: "email"`	-
locale	UserLocale	Yes	-	The account's UI language preference.
path	string	No	-	-
userAgent	string	No	-	-
createdAt	string	Yes	`format: "date-time"`	-

AccountDataExportGrid

A grid belonging to the workshop, as stored.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
name	string	Yes	-	-
iconSize	string	Yes	enum`"small""medium""large"`	-
createdAt	string	Yes	`format: "date-time"`	-
updatedAt	string	Yes	`format: "date-time"`	-
buttons	array of AccountDataExportGridButton	Yes	-	-

AccountDataExportGridButton

One button on a grid, as stored.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
emoji	string	Yes	-	-
label	string	Yes	-	-
unit	string	Yes	enum`"sqm""linear_m""piece""pair""hour""job""freeform"`	-
unitPrice	number	Yes	-	-
backgroundColor	string	No	-	-
iconFileId	string	No	-	-

AccountDataExportLineItem

One line item on an estimate or one of its revisions, as stored.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
label	string	Yes	-	-
unit	string	Yes	enum`"sqm""linear_m""piece""pair""hour""job""freeform"`	-
unitPrice	number	Yes	-	-
quantity	number	Yes	-	-
sourceButtonId	string	No	-	-

AccountDataExportOrder

An order belonging to the workshop, as stored.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
title	string	Yes	-	-
customerName	string	Yes	-	-
notes	string	Yes	-	-
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAt	string	Yes	`format: "date-time"`	-
lastActivityAt	string	Yes	`format: "date-time"`	-
statusHistory	array of OrderStatusHistoryEntry	Yes	-	-

AccountDataExportUser

The account record as stored, minus authentication method secrets.

Field	Type	Required	Constraints	Description
uid	string	Yes	-	-
email	string	Yes	`format: "email"`	-
name	string	Yes	-	-
status	string	Yes	enum`"pending""active""suspended""deleted"`	-
emailVerifiedAt	string \| null	Yes	-	-
termsVersion	string	No	-	-
termsAcceptedAt	string	No	`format: "date-time"`	-
lastLoginAt	string	No	`format: "date-time"`	-
locale	UserLocale	No	-	The account's UI language preference.

AccountDataExportWorkshop

A workshop the account owns or belongs to, as stored: unlike the public Workshop resource this includes the raw billing ids and the AI rate-limit attempt timestamps, since this endpoint exports the record as kept, not the trimmed member-facing view.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
name	string	Yes	-	-
tagline	string	Yes	-	-
logo	string	Yes	-	-
crafterName	string	Yes	-	-
crafterAvatarSeed	string	Yes	-	-
background	Background	Yes	-	A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackground	WorkshopCustomBackground	No	-	A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFont	TitleFont	Yes	-	A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColor	HexColor \| null	No	-	-
plan	WorkshopPlan	No	-	The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAt	string \| null	No	-	-
planSource	WorkshopPlanSource \| null	No	-	-
billingCustomerId	string	No	-	-
billingSubscriptionId	string \| null	No	-	-
billingCancelAtPeriodEnd	boolean	No	-	-
context	WorkshopContext	No	-	The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.
contextDerived	WorkshopContextDerived	No	-	The AI-synthesized summary and suggested intents distilled from the workshop's context notes.
contextSynthesisAttempts	array of string	No	-	-
messageDraftAttempts	array of string	No	-	-
isDefault	boolean	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-

AccountDataExportWorkshopEntry

One owned or joined workshop and everything in it.

Field	Type	Required	Constraints	Description
workshop	AccountDataExportWorkshop	Yes	-	A workshop the account owns or belongs to, as stored: unlike the public Workshop resource this includes the raw billing ids and the AI rate-limit attempt timestamps, since this endpoint exports the record as kept, not the trimmed member-facing view.
grids	array of AccountDataExportGrid	Yes	-	-
estimates	array of AccountDataExportEstimate	Yes	-	-
orders	array of AccountDataExportOrder	Yes	-	-

AuthenticatedUser

The signed-in account, as returned by the endpoint that grants the session.

Field	Type	Required	Constraints	Description
uid	string	Yes	-	-
email	string	Yes	`format: "email"`	-
name	string	Yes	-	-
locale	UserLocale	Yes	-	The account's UI language preference.

AuthenticateResponse

Field	Type	Required	Constraints	Description
user	AuthenticatedUser	Yes	-	The signed-in account, as returned by the endpoint that grants the session.

Background

A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.

string

enum"paper""linen""sage""mist""blush""indigo""forest""plum""terracotta""charcoal""astral""ember""meadow""dusk""tide""orchid""copper""aurora""dawn""cloud"

DocumentLocale

The language a generated estimate PDF or hand-off message is written in: pl (Polish) or en (English).

string

enum"pl""en"

Emoji

One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).

string

minLength: 1

Estimate

An estimate as returned to a member. Confirming it (see the confirm endpoint) snapshots this content into a new revision; nothing about the estimate itself records whether it has ever been confirmed.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
name	string	Yes	-	-
recipientName	string	No	-	Absent when the estimate has no named recipient
createdAt	string	Yes	`format: "date-time"`	-
updatedAt	string	Yes	`format: "date-time"`	-
markupPercent	number	Yes	-	-
discountPercent	number	Yes	-	-
lineItems	array of LineItem	Yes	-	-

EstimateConfirmation

Field	Type	Required	Constraints	Description
estimate	Estimate	Yes	-	An estimate as returned to a member. Confirming it (see the confirm endpoint) snapshots this content into a new revision; nothing about the estimate itself records whether it has ever been confirmed.
revision	EstimateRevision	Yes	-	A snapshot of an estimate's content at the moment it was confirmed, numbered from 1.

EstimateRevision

A snapshot of an estimate's content at the moment it was confirmed, numbered from 1.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
revisionNumber	number	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-
createdByUid	string	Yes	-	-
name	string	Yes	-	-
markupPercent	number	Yes	-	-
discountPercent	number	Yes	-	-
lineItems	array of LineItem	Yes	-	-

EstimateRevisionsList

Field	Type	Required	Constraints	Description
revisions	array of EstimateRevision	Yes	-	-

EstimatesList

Field	Type	Required	Constraints	Description
estimates	array of Estimate	Yes	-	-

FeedbackKind

Whether the message is general feedback or a support request.

string

enum"feedback""support"

FileCategory

What a file is used for. Decides the accepted content types and any per-file size cap: grid_tile_icon (an image attached to a grid button, up to 512 KB) or estimate_pdf (a generated estimate PDF, no per-file cap).

string

enum"grid_tile_icon""estimate_pdf"

FileRecord

A stored file's metadata. Omits the internal GCS storage path; download the bytes through GET /files/{fileId}.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
scope	FileScope	Yes	-	The kind of resource a file is authorized against: workshop or estimate. Both categories accepted by POST /files resolve to workshop; estimate-scoped files are created by other endpoints, not this one.
scopeId	string	Yes	-	-
category	FileCategory	Yes	-	What a file is used for. Decides the accepted content types and any per-file size cap: grid_tile_icon (an image attached to a grid button, up to 512 KB) or estimate_pdf (a generated estimate PDF, no per-file cap).
name	string	No	-	-
contentType	string	Yes	-	-
sizeBytes	integer	Yes	`minimum: -9007199254740991maximum: 9007199254740991`	-
uploadedByUid	string	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-
estimateId	string	No	-	Set only for files created against an estimate scope.

FileScope

The kind of resource a file is authorized against: workshop or estimate. Both categories accepted by POST /files resolve to workshop; estimate-scoped files are created by other endpoints, not this one.

string

enum"estimate""workshop"

FilesList

Field	Type	Required	Constraints	Description
files	array of FileRecord	Yes	-	-

Grid

A grid as returned to a member: a named board of priceable buttons, capped at 10 per workshop.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
name	string	Yes	-	-
iconSize	GridIconSize	Yes	-	A grid's icon size, one of these three values.
createdAt	string	Yes	`format: "date-time"`	-
updatedAt	string	Yes	`format: "date-time"`	-
buttons	array of GridButton	Yes	-	-

GridButton

One priceable button on a grid. unit and unitPrice become the sourceButtonId'd line item's defaults when added to an estimate.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
emoji	Emoji	Yes	-	One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
label	string	Yes	-	-
unit	LineItemUnit	Yes	-	A line item's unit of measure, one of these seven values.
unitPrice	number	Yes	-	-
backgroundColor	HexColor	No	-	Absent when the button has no background override
iconFileId	string	No	-	Id of a file uploaded through POST /files with category grid_tile_icon. Absent when the button has no icon.

GridIconInUse

The ids of every grid in the workshop with a button still referencing this icon.

Field	Type	Required	Constraints	Description
gridIds	array of string	Yes	-	-

GridIconSize

A grid's icon size, one of these three values.

string

enum"small""medium""large"

GridsList

Field	Type	Required	Constraints	Description
grids	array of Grid	Yes	-	-

GridTemplate

A named starting set of catalog items for one domain, ready to turn into a grid's buttons.

Field	Type	Required	Constraints	Description
slug	string	Yes	-	-
domainSlug	string	Yes	-	References a PredefinedItemDomain's slug, by string match, not enforced
name	LocalizedText	Yes	-	The same text in English and Polish.
description	LocalizedText	Yes	-	The same text in English and Polish.
itemIds	array of string	Yes	-	References PredefinedGridItem ids, by string match, not enforced

Handoff

A record that an estimate was handed off to its recipient somehow - not the message or PDF itself, just that it happened, when, how and in what tone.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
kind	HandoffKind	Yes	-	How a crafter delivered an estimate to its recipient, one of these five values: message-copied, message-shared, pdf-shared, pdf-and-message-shared or email-opened. Caller-supplied and not verified against anything that actually happened, see the hand-off endpoint's own description.
locale	DocumentLocale	Yes	-	The language a generated estimate PDF or hand-off message is written in: pl (Polish) or en (English).
preliminary	boolean	Yes	-	-
tone	MessageTone	Yes	-	The tone of a hand-off message, formal or friendly. Recorded on every hand-off regardless of aiDrafted, not just ones whose text came from the AI draft endpoint.
aiDrafted	boolean	Yes	-	Whether the delivered message text came from POST .../message-draft rather than being hand-written.
revisionNumber	number	Yes	-	The estimate's latest revision number at the time of hand-off.
createdAt	string	Yes	`format: "date-time"`	-
createdByUid	string	Yes	-	-
pdfExportId	string	No	-	The pdf export this hand-off refers to, when one was involved. Absent otherwise.

HandoffKind

How a crafter delivered an estimate to its recipient, one of these five values: message-copied, message-shared, pdf-shared, pdf-and-message-shared or email-opened. Caller-supplied and not verified against anything that actually happened, see the hand-off endpoint's own description.

string

enum"message-copied""message-shared""pdf-shared""pdf-and-message-shared""email-opened"

HandoffsList

Field	Type	Required	Constraints	Description
handoffs	array of Handoff	Yes	-	-

HexColor

A #RRGGBB hex color.

string

pattern: "^#[0-9A-Fa-f]{6}
quot;

LineItem

One priced line on an estimate.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
label	string	Yes	-	-
unit	LineItemUnit	Yes	-	A line item's unit of measure, one of these seven values.
unitPrice	number	Yes	-	-
quantity	number	Yes	-	-
sourceButtonId	string	No	-	The grid button this line item was added from, when it was. Not validated on write.

LineItemUnit

A line item's unit of measure, one of these seven values.

string

enum"sqm""linear_m""piece""pair""hour""job""freeform"

LocalizedText

The same text in English and Polish.

Field	Type	Required	Constraints	Description
en	string	Yes	-	-
pl	string	Yes	-	-

MeProfile

The signed-in account's own profile.

Field	Type	Required	Constraints	Description
name	string	Yes	-	-
email	string	Yes	`format: "email"`	-
locale	UserLocale	Yes	-	The account's UI language preference.
signInMethods	array of SignInMethod	Yes	-	-

MessageTone

The tone of a hand-off message, formal or friendly. Recorded on every hand-off regardless of aiDrafted, not just ones whose text came from the AI draft endpoint.

string

enum"formal""friendly"

MostUsedLineItemsList

Field	Type	Required	Constraints	Description
lineItems	array of object	Yes	-	-
lineItems[].label	string	Yes	-	-
lineItems[].unit	LineItemUnit	Yes	-	A line item's unit of measure, one of these seven values.
lineItems[].unitPrice	number	Yes	-	-
lineItems[].count	number	Yes	-	How many of the workshop's estimates use a line item with this label and unit
lineItems[].lastUsedAt	string	Yes	`format: "date-time"`	The updatedAt of the most recent estimate that uses it

Order

An order as returned to a member: title, customer name and notes are edited in place through this same shape, status changes are recorded in statusHistory.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
workshopId	string	Yes	-	-
title	string	Yes	-	-
customerName	string	Yes	-	Blank when the order has no named customer
notes	string	Yes	-	-
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAt	string	Yes	`format: "date-time"`	-
lastActivityAt	string	Yes	`format: "date-time"`	-
statusHistory	array of OrderStatusHistoryEntry	Yes	-	-

OrdersList

Field	Type	Required	Constraints	Description
orders	array of Order	Yes	-	-

OrderStatus

An order's stage, always one of these three values in this order: todo, in_progress, done.

string

enum"todo""in_progress""done"

OrderStatusHistoryEntry

One entry in an order's status history: the status it moved to and when.

Field	Type	Required	Constraints	Description
status	OrderStatus	Yes	-	An order's stage, always one of these three values in this order: todo, in_progress, done.
at	string	Yes	`format: "date-time"`	-

PdfExport

Metadata for one generated estimate PDF; this shape never carries the file's bytes, download them with GET /estimates/{estimateId}/pdf-exports/{pdfExportId}.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
revisionNumber	number	Yes	-	The estimate's latest revision number at the time of export.
toggles	PdfExportOptions	Yes	-	The visual toggles for a generated estimate PDF, each defaulting server-side when omitted.
generatedAt	string	Yes	`format: "date-time"`	-
createdByUid	string	Yes	-	-
locale	DocumentLocale	No	-	Absent only on a pdf export generated before locale was tracked.
preliminary	boolean	No	-	Absent only on a pdf export generated before preliminary was tracked.

PdfExportOptions

The visual toggles for a generated estimate PDF, each defaulting server-side when omitted.

Field	Type	Required	Constraints	Description
breakdown	boolean	Yes	`default: true`	Include the itemized line-item breakdown table.
showMarkup	boolean	Yes	`default: false`	Show the markup percentage and amount.
showDiscount	boolean	Yes	`default: false`	Show the discount percentage and amount.
showRecipient	boolean	Yes	`default: true`	Show the recipient's name.
showBrandMark	boolean	Yes	`default: true`	Show Mercastra's brand mark. A workshop whose plan cannot disable it (see entitlements) has this forced back to true server-side regardless of what is sent.

PdfExportsList

Field	Type	Required	Constraints	Description
pdfExports	array of PdfExport	Yes	-	-

PredefinedGridItem

One reference item a grid button can be built from: a label, a default unit and free-text tags.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
emoji	Emoji	Yes	-	One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
label	LocalizedText	Yes	-	The same text in English and Polish.
unit	LineItemUnit	Yes	-	A line item's unit of measure, one of these seven values.
tags	array of string	Yes	-	-

PredefinedItemDomain

One craft domain grouping catalog items and templates, for example woodworking-and-carpentry.

Field	Type	Required	Constraints	Description
slug	string	Yes	-	-
label	LocalizedText	Yes	-	The same text in English and Polish.

PredefinedItemsCatalog

Field	Type	Required	Constraints	Description
items	array of PredefinedGridItem	Yes	-	-
domains	array of PredefinedItemDomain	Yes	-	-
templates	array of GridTemplate	Yes	-	-

SignInMethod

A way the account can authenticate: a password, or a linked OAuth provider.

string

enum"password""google"

TitleFont

A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.

string

enum"sans""serif""didone""mono""rounded"

UserLocale

The account's UI language preference.

string

enum"en""pl"

Workshop

A workshop as returned to a member: billing ids and AI rate-limit attempt lists are stripped, the plan is already resolved for expiry.

Field	Type	Required	Constraints	Description
id	string	Yes	-	-
name	string	Yes	-	-
tagline	string	Yes	-	-
logo	string	Yes	-	One emoji from the curated icon set
crafterName	string	Yes	-	-
crafterAvatarSeed	string	Yes	-	-
background	Background	Yes	-	A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackground	WorkshopCustomBackground	No	-	A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFont	TitleFont	Yes	-	A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColor	HexColor \| null	No	-	-
plan	WorkshopPlan	Yes	-	The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAt	string \| null	No	-	Set while `plan` is a time-boxed Pro (a trial or a paid subscription's current period); null on a permanent plan
planSource	WorkshopPlanSource \| null	No	-	-
context	WorkshopContext	No	-	The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.
contextDerived	WorkshopContextDerived	No	-	The AI-synthesized summary and suggested intents distilled from the workshop's context notes.
isDefault	boolean	Yes	-	-
members	array of WorkshopMember	Yes	-	-
createdAt	string	Yes	`format: "date-time"`	-

WorkshopBilling

Field	Type	Required	Constraints	Description
hasAccount	boolean	Yes	-	True once a payment-provider customer exists for the workshop
planSource	WorkshopPlanSource \| null	Yes	-	-
cancelAtPeriodEnd	boolean	Yes	-	True only for a subscription the customer already canceled at the provider
checkoutAvailability	string	Yes	enum`"available""pro_purchase_disabled""payments_not_configured"`	-

WorkshopContext

The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.

Field	Type	Required	Constraints	Description
notes	string	Yes	-	-
updatedAt	string	Yes	`format: "date-time"`	-

WorkshopContextDerived

The AI-synthesized summary and suggested intents distilled from the workshop's context notes.

Field	Type	Required	Constraints	Description
summary	LocalizedText	Yes	-	At most 400 characters per language
suggestedIntents	object	Yes	`additionalProperties: false`	3 to 5 entries per language, at most 80 characters each
suggestedIntents.en	array of string	Yes	-	-
suggestedIntents.pl	array of string	Yes	-	-
sourceUpdatedAt	string	Yes	`format: "date-time"`	The `context.updatedAt` this was derived from
generatedAt	string	Yes	`format: "date-time"`	-

WorkshopCustomBackground

A freeform solid or gradient background overriding the preset `background` id, or null for no override.

object | object | null

WorkshopEntitlementsUsage

The workshop's plan entitlements and current quota usage, derived from stored state only.

Field	Type	Required	Constraints	Description
plan	WorkshopPlan	Yes	-	The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAt	string \| null	Yes	-	-
brandMark	object	Yes	`additionalProperties: false`	-
brandMark.canDisable	boolean	Yes	-	-
fileStorage	object	Yes	`additionalProperties: false`	-
fileStorage.usedBytes	number	Yes	-	-
fileStorage.limitBytes	number	Yes	-	-
revisions	object	Yes	`additionalProperties: false`	null means unlimited (Pro); the value is per estimate, it carries no usage counter
revisions.limitPerEstimate	number \| null	Yes	-	-
billing	WorkshopBilling	Yes	-	-

WorkshopMember

A workshop member, resolved from its membership record.

Field	Type	Required	Constraints	Description
id	string	Yes	-	The member's user id
name	string	Yes	-	-
avatarSeed	string	Yes	-	-
role	string	Yes	enum`"owner""member"`	-

WorkshopPlan

The workshop's resolved plan; an expired time-boxed Pro reads back as free.

string

enum"free""pro"

WorkshopPlanSource

What granted the current Pro plan: a founder CLI grant, the mocked self-serve trial, or a paid subscription.

string

enum"grant""trial""subscription"

WorkshopsList

Field	Type	Required	Constraints	Description
workshops	array of Workshop	Yes	-	-