Workshops

4 endpointsEnglish only

List the caller's workshops

get/workshopsexperimentalSession required

Returns every workshop the caller is a member of. Each workshop carries its resolved `plan`, its `context` when notes have been saved and, once synthesized, its `contextDerived`.

Responses

200Success

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

Example

{
  "workshops": [
    {
      "id": "workshop-1",
      "name": "Extremely Awesome Workshop",
      "tagline": "Solid-wood furniture, built to order",
      "logo": "🛠️",
      "crafterName": "Kamil",
      "crafterAvatarSeed": "uid-1",
      "background": "paper",
      "titleFont": "sans",
      "accentColor": null,
      "plan": "free",
      "planExpiresAt": null,
      "planSource": null,
      "isDefault": true,
      "members": [
        {
          "id": "uid-1",
          "name": "Kamil",
          "avatarSeed": "uid-1",
          "role": "owner"
        }
      ],
      "createdAt": "2026-07-04T00:00:00.000Z"
    }
  ]
}

401Not authenticated
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/workshops' \
  -H 'Cookie: session=<session cookie>'

Update the workshop's profile

patch/workshops/{workshopId}experimentalSession required

Updates the workshop's profile fields: name, tagline, logo, crafter name, background, custom background, title font and accent color. The body is strict, an unknown field is a 400 - `plan` is never accepted here, it is written only by the founder-side plan grant tooling. `background` and `titleFont` are preset ids validated against a fixed list; `customBackground` and `accentColor` are freeform #RRGGBB hex, with null/absent meaning no override. Responds 403 when the caller is not a member of the workshop and 404 when no such workshop exists.

Path parameters

Name	Type	Required	Constraints	Description
workshopId	string	Yes	-	Workshop id

Request body

Field	Type	Required	Constraints	Description
name	string	No	`minLength: 1`	-
tagline	string	No	`maxLength: 250`	At most 250 characters
logo	Emoji	No	-	One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
crafterName	string	No	-	-
background	Background	No	-	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	No	-	A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColor	HexColor \| null	No	-	-

Example

{
  "tagline": "Solid-wood furniture, built to order",
  "accentColor": "#6D5BD0"
}

Responses

200Success

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"`	-

Example

{
  "id": "workshop-1",
  "name": "Extremely Awesome Workshop",
  "tagline": "Solid-wood furniture, built to order",
  "logo": "🛠️",
  "crafterName": "Kamil",
  "crafterAvatarSeed": "uid-1",
  "background": "paper",
  "titleFont": "sans",
  "accentColor": "#6D5BD0",
  "plan": "free",
  "planExpiresAt": null,
  "planSource": null,
  "isDefault": true,
  "members": [
    {
      "id": "uid-1",
      "name": "Kamil",
      "avatarSeed": "uid-1",
      "role": "owner"
    }
  ],
  "createdAt": "2026-07-04T00:00:00.000Z"
}

400The request body does not match the schema
The shared validation error body, see Validation errors.
401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X PATCH 'https://mercastra.cloud/api/workshops/<workshopId>' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>' \
  -H 'Content-Type: application/json' \
  -d '{"tagline":"Solid-wood furniture, built to order","accentColor":"#6D5BD0"}'

Replace the workshop's context notes

put/workshops/{workshopId}/contextexperimentalSession required

Stores free-text notes describing the workshop: what it makes, how it works and anything Mercastra should know to tailor its work to it, price grids or customer messages for example. Whitespace around the notes is trimmed and the whole value is replaced, an empty string clears it. The notes feed summaries derived later, saving them triggers nothing by itself. Responds 403 when the caller is not a member of the workshop and 404 when no such workshop exists.

Path parameters

Name	Type	Required	Constraints	Description
workshopId	string	Yes	-	Workshop id

Request body

Field	Type	Required	Constraints	Description
notes	string	Yes	`maxLength: 4000`	Free-text notes about the workshop, trimmed, at most 4000 UTF-16 code units

Example

{
  "notes": "I build solid-wood furniture to order. Two-week lead time."
}

Responses

200Success

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

Example

{
  "notes": "I build solid-wood furniture to order. Two-week lead time.",
  "updatedAt": "2026-09-05T10:00:00.000Z"
}

400The request body does not match the schema
The shared validation error body, see Validation errors.
401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X PUT 'https://mercastra.cloud/api/workshops/<workshopId>/context' \
  -H 'Cookie: session=<session cookie>' \
  -H 'X-CSRF-Token: <csrf-token cookie value>' \
  -H 'Content-Type: application/json' \
  -d '{"notes":"I build solid-wood furniture to order. Two-week lead time."}'

Read the workshop's plan entitlements and quota usage

get/workshops/{workshopId}/entitlementsexperimentalSession required

Read-only view of the workshop's plan entitlements and quota usage - what the plan-management page renders. Never calls the payment provider, everything is derived from stored state. Responds 403 when the caller is not a member of the workshop and 404 when no such workshop exists.

Path parameters

Name	Type	Required	Constraints	Description
workshopId	string	Yes	-	Workshop id

Responses

200Success

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

Example

{
  "plan": "free",
  "planExpiresAt": null,
  "brandMark": {
    "canDisable": false
  },
  "fileStorage": {
    "usedBytes": 5242880,
    "limitBytes": 10485760
  },
  "revisions": {
    "limitPerEstimate": 5
  },
  "billing": {
    "hasAccount": false,
    "planSource": null,
    "cancelAtPeriodEnd": false,
    "checkoutAvailability": "available"
  }
}

401Not authenticated
No body.
403Forbidden
No body.
404Not found
No body.

Example request

curl -X GET 'https://mercastra.cloud/api/workshops/<workshopId>/entitlements' \
  -H 'Cookie: session=<session cookie>'