Schematy

Nazwane kształty, do których odsyłają pola REST API: każda encja i model, udokumentowane raz zamiast powtarzane przy każdym użyciu.

66 schematówTylko po angielsku

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.

PoleTypWymaganeOgraniczeniaOpis
userAccountDataExportUserTak-The account record as stored, minus authentication method secrets.
workshopsarray of AccountDataExportWorkshopEntryTak--
feedbackarray of AccountDataExportFeedbackTak--
authProvidersarray of AccountDataExportAuthProviderTak--

AccountDataExportAuthProvider

A linked OAuth provider identity, as stored.

PoleTypWymaganeOgraniczeniaOpis
providerstringTakconst: "google"-
subjectstringTak--
linkedAtstringTakformat: "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).

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
namestringTak--
recipientNamestringNie--
createdAtstringTakformat: "date-time"-
updatedAtstringTakformat: "date-time"-
markupPercentnumberTak--
discountPercentnumberTak--
lineItemsarray of AccountDataExportLineItemTak--
revisionsarray of AccountDataExportEstimateRevisionTak--

AccountDataExportEstimateRevision

A saved revision of an estimate, as stored.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
revisionNumbernumberTak--
createdAtstringTakformat: "date-time"-
createdByUidstringTak--
namestringTak--
markupPercentnumberTak--
discountPercentnumberTak--
lineItemsarray of AccountDataExportLineItemTak--

AccountDataExportFeedback

One feedback or support message the account submitted.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
kindFeedbackKindTak-Whether the message is general feedback or a support request.
titlestringTak--
messagestringTak--
emailstringTakformat: "email"-
localeUserLocaleTak-The account's UI language preference.
pathstringNie--
userAgentstringNie--
createdAtstringTakformat: "date-time"-

AccountDataExportGrid

A grid belonging to the workshop, as stored.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
namestringTak--
iconSizestringTakenum"small""medium""large"-
createdAtstringTakformat: "date-time"-
updatedAtstringTakformat: "date-time"-
buttonsarray of AccountDataExportGridButtonTak--

AccountDataExportGridButton

One button on a grid, as stored.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
emojistringTak--
labelstringTak--
unitstringTakenum"sqm""linear_m""piece""pair""hour""job""freeform"-
unitPricenumberTak--
backgroundColorstringNie--
iconFileIdstringNie--

AccountDataExportLineItem

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

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
labelstringTak--
unitstringTakenum"sqm""linear_m""piece""pair""hour""job""freeform"-
unitPricenumberTak--
quantitynumberTak--
sourceButtonIdstringNie--

AccountDataExportOrder

An order belonging to the workshop, as stored.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
titlestringTak--
customerNamestringTak--
notesstringTak--
statusOrderStatusTak-An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAtstringTakformat: "date-time"-
lastActivityAtstringTakformat: "date-time"-
statusHistoryarray of OrderStatusHistoryEntryTak--

AccountDataExportUser

The account record as stored, minus authentication method secrets.

PoleTypWymaganeOgraniczeniaOpis
uidstringTak--
emailstringTakformat: "email"-
namestringTak--
statusstringTakenum"pending""active""suspended""deleted"-
emailVerifiedAtstring | nullTak--
termsVersionstringNie--
termsAcceptedAtstringNieformat: "date-time"-
lastLoginAtstringNieformat: "date-time"-
localeUserLocaleNie-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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
namestringTak--
taglinestringTak--
logostringTak--
crafterNamestringTak--
crafterAvatarSeedstringTak--
backgroundBackgroundTak-A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackgroundWorkshopCustomBackgroundNie-A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFontTitleFontTak-A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColorHexColor | nullNie--
planWorkshopPlanNie-The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAtstring | nullNie--
planSourceWorkshopPlanSource | nullNie--
billingCustomerIdstringNie--
billingSubscriptionIdstring | nullNie--
billingCancelAtPeriodEndbooleanNie--
contextWorkshopContextNie-The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.
contextDerivedWorkshopContextDerivedNie-The AI-synthesized summary and suggested intents distilled from the workshop's context notes.
contextSynthesisAttemptsarray of stringNie--
messageDraftAttemptsarray of stringNie--
isDefaultbooleanTak--
createdAtstringTakformat: "date-time"-

AccountDataExportWorkshopEntry

One owned or joined workshop and everything in it.

PoleTypWymaganeOgraniczeniaOpis
workshopAccountDataExportWorkshopTak-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.
gridsarray of AccountDataExportGridTak--
estimatesarray of AccountDataExportEstimateTak--
ordersarray of AccountDataExportOrderTak--

AuthenticatedUser

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

PoleTypWymaganeOgraniczeniaOpis
uidstringTak--
emailstringTakformat: "email"-
namestringTak--
localeUserLocaleTak-The account's UI language preference.

AuthenticateResponse

PoleTypWymaganeOgraniczeniaOpis
userAuthenticatedUserTak-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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
namestringTak--
recipientNamestringNie-Absent when the estimate has no named recipient
createdAtstringTakformat: "date-time"-
updatedAtstringTakformat: "date-time"-
markupPercentnumberTak--
discountPercentnumberTak--
lineItemsarray of LineItemTak--

EstimateConfirmation

PoleTypWymaganeOgraniczeniaOpis
estimateEstimateTak-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.
revisionEstimateRevisionTak-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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
revisionNumbernumberTak--
createdAtstringTakformat: "date-time"-
createdByUidstringTak--
namestringTak--
markupPercentnumberTak--
discountPercentnumberTak--
lineItemsarray of LineItemTak--

EstimateRevisionsList

PoleTypWymaganeOgraniczeniaOpis
revisionsarray of EstimateRevisionTak--

EstimatesList

PoleTypWymaganeOgraniczeniaOpis
estimatesarray of EstimateTak--

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}.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
scopeFileScopeTak-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.
scopeIdstringTak--
categoryFileCategoryTak-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).
namestringNie--
contentTypestringTak--
sizeBytesintegerTakminimum: -9007199254740991maximum: 9007199254740991-
uploadedByUidstringTak--
createdAtstringTakformat: "date-time"-
estimateIdstringNie-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

PoleTypWymaganeOgraniczeniaOpis
filesarray of FileRecordTak--

Grid

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

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
namestringTak--
iconSizeGridIconSizeTak-A grid's icon size, one of these three values.
createdAtstringTakformat: "date-time"-
updatedAtstringTakformat: "date-time"-
buttonsarray of GridButtonTak--

GridButton

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

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
emojiEmojiTak-One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
labelstringTak--
unitLineItemUnitTak-A line item's unit of measure, one of these seven values.
unitPricenumberTak--
backgroundColorHexColorNie-Absent when the button has no background override
iconFileIdstringNie-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.

PoleTypWymaganeOgraniczeniaOpis
gridIdsarray of stringTak--

GridIconSize

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

string
enum"small""medium""large"

GridsList

PoleTypWymaganeOgraniczeniaOpis
gridsarray of GridTak--

GridTemplate

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

PoleTypWymaganeOgraniczeniaOpis
slugstringTak--
domainSlugstringTak-References a PredefinedItemDomain's slug, by string match, not enforced
nameLocalizedTextTak-The same text in English and Polish.
descriptionLocalizedTextTak-The same text in English and Polish.
itemIdsarray of stringTak-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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
kindHandoffKindTak-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.
localeDocumentLocaleTak-The language a generated estimate PDF or hand-off message is written in: pl (Polish) or en (English).
preliminarybooleanTak--
toneMessageToneTak-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.
aiDraftedbooleanTak-Whether the delivered message text came from POST .../message-draft rather than being hand-written.
revisionNumbernumberTak-The estimate's latest revision number at the time of hand-off.
createdAtstringTakformat: "date-time"-
createdByUidstringTak--
pdfExportIdstringNie-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

PoleTypWymaganeOgraniczeniaOpis
handoffsarray of HandoffTak--

HexColor

A #RRGGBB hex color.

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

LineItem

One priced line on an estimate.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
labelstringTak--
unitLineItemUnitTak-A line item's unit of measure, one of these seven values.
unitPricenumberTak--
quantitynumberTak--
sourceButtonIdstringNie-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.

PoleTypWymaganeOgraniczeniaOpis
enstringTak--
plstringTak--

MeProfile

The signed-in account's own profile.

PoleTypWymaganeOgraniczeniaOpis
namestringTak--
emailstringTakformat: "email"-
localeUserLocaleTak-The account's UI language preference.
signInMethodsarray of SignInMethodTak--

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

PoleTypWymaganeOgraniczeniaOpis
lineItemsarray of objectTak--
lineItems[].labelstringTak--
lineItems[].unitLineItemUnitTak-A line item's unit of measure, one of these seven values.
lineItems[].unitPricenumberTak--
lineItems[].countnumberTak-How many of the workshop's estimates use a line item with this label and unit
lineItems[].lastUsedAtstringTakformat: "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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
workshopIdstringTak--
titlestringTak--
customerNamestringTak-Blank when the order has no named customer
notesstringTak--
statusOrderStatusTak-An order's stage, always one of these three values in this order: todo, in_progress, done.
createdAtstringTakformat: "date-time"-
lastActivityAtstringTakformat: "date-time"-
statusHistoryarray of OrderStatusHistoryEntryTak--

OrdersList

PoleTypWymaganeOgraniczeniaOpis
ordersarray of OrderTak--

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.

PoleTypWymaganeOgraniczeniaOpis
statusOrderStatusTak-An order's stage, always one of these three values in this order: todo, in_progress, done.
atstringTakformat: "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}.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
revisionNumbernumberTak-The estimate's latest revision number at the time of export.
togglesPdfExportOptionsTak-The visual toggles for a generated estimate PDF, each defaulting server-side when omitted.
generatedAtstringTakformat: "date-time"-
createdByUidstringTak--
localeDocumentLocaleNie-Absent only on a pdf export generated before locale was tracked.
preliminarybooleanNie-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.

PoleTypWymaganeOgraniczeniaOpis
breakdownbooleanTakdefault: trueInclude the itemized line-item breakdown table.
showMarkupbooleanTakdefault: falseShow the markup percentage and amount.
showDiscountbooleanTakdefault: falseShow the discount percentage and amount.
showRecipientbooleanTakdefault: trueShow the recipient's name.
showBrandMarkbooleanTakdefault: trueShow 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

PoleTypWymaganeOgraniczeniaOpis
pdfExportsarray of PdfExportTak--

PredefinedGridItem

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

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
emojiEmojiTak-One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
labelLocalizedTextTak-The same text in English and Polish.
unitLineItemUnitTak-A line item's unit of measure, one of these seven values.
tagsarray of stringTak--

PredefinedItemDomain

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

PoleTypWymaganeOgraniczeniaOpis
slugstringTak--
labelLocalizedTextTak-The same text in English and Polish.

PredefinedItemsCatalog

PoleTypWymaganeOgraniczeniaOpis
itemsarray of PredefinedGridItemTak--
domainsarray of PredefinedItemDomainTak--
templatesarray of GridTemplateTak--

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.

PoleTypWymaganeOgraniczeniaOpis
idstringTak--
namestringTak--
taglinestringTak--
logostringTak-One emoji from the curated icon set
crafterNamestringTak--
crafterAvatarSeedstringTak--
backgroundBackgroundTak-A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackgroundWorkshopCustomBackgroundNie-A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFontTitleFontTak-A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColorHexColor | nullNie--
planWorkshopPlanTak-The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAtstring | nullNie-Set while `plan` is a time-boxed Pro (a trial or a paid subscription's current period); null on a permanent plan
planSourceWorkshopPlanSource | nullNie--
contextWorkshopContextNie-The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.
contextDerivedWorkshopContextDerivedNie-The AI-synthesized summary and suggested intents distilled from the workshop's context notes.
isDefaultbooleanTak--
membersarray of WorkshopMemberTak--
createdAtstringTakformat: "date-time"-

WorkshopBilling

PoleTypWymaganeOgraniczeniaOpis
hasAccountbooleanTak-True once a payment-provider customer exists for the workshop
planSourceWorkshopPlanSource | nullTak--
cancelAtPeriodEndbooleanTak-True only for a subscription the customer already canceled at the provider
checkoutAvailabilitystringTakenum"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.

PoleTypWymaganeOgraniczeniaOpis
notesstringTak--
updatedAtstringTakformat: "date-time"-

WorkshopContextDerived

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

PoleTypWymaganeOgraniczeniaOpis
summaryLocalizedTextTak-At most 400 characters per language
suggestedIntentsobjectTakadditionalProperties: false3 to 5 entries per language, at most 80 characters each
suggestedIntents.enarray of stringTak--
suggestedIntents.plarray of stringTak--
sourceUpdatedAtstringTakformat: "date-time"The `context.updatedAt` this was derived from
generatedAtstringTakformat: "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.

PoleTypWymaganeOgraniczeniaOpis
planWorkshopPlanTak-The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAtstring | nullTak--
brandMarkobjectTakadditionalProperties: false-
brandMark.canDisablebooleanTak--
fileStorageobjectTakadditionalProperties: false-
fileStorage.usedBytesnumberTak--
fileStorage.limitBytesnumberTak--
revisionsobjectTakadditionalProperties: falsenull means unlimited (Pro); the value is per estimate, it carries no usage counter
revisions.limitPerEstimatenumber | nullTak--
billingWorkshopBillingTak--

WorkshopMember

A workshop member, resolved from its membership record.

PoleTypWymaganeOgraniczeniaOpis
idstringTak-The member's user id
namestringTak--
avatarSeedstringTak--
rolestringTakenum"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

PoleTypWymaganeOgraniczeniaOpis
workshopsarray of WorkshopTak--