Workshops

4 endpointyTylko po angielsku

List the caller's workshops

get/workshopsexperimentalWymagana sesja

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

Odpowiedzi

200Success

Pole	Typ	Wymagane	Ograniczenia	Opis
workshops	array of Workshop	Tak	-	-

Przykład

{
  "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
Brak treści.

Przykładowe żądanie

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

Update the workshop's profile

patch/workshops/{workshopId}experimentalWymagana sesja

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.

Parametry ścieżki

Nazwa	Typ	Wymagane	Ograniczenia	Opis
workshopId	string	Tak	-	Workshop id

Treść żądania

Pole	Typ	Wymagane	Ograniczenia	Opis
name	string	Nie	`minLength: 1`	-
tagline	string	Nie	`maxLength: 250`	At most 250 characters
logo	Emoji	Nie	-	One emoji from Mercastra's curated icon set (see EMOJI_CATEGORIES).
crafterName	string	Nie	-	-
background	Background	Nie	-	A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackground	WorkshopCustomBackground	Nie	-	A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFont	TitleFont	Nie	-	A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColor	HexColor \| null	Nie	-	-

Przykład

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

Odpowiedzi

200Success

Pole	Typ	Wymagane	Ograniczenia	Opis
id	string	Tak	-	-
name	string	Tak	-	-
tagline	string	Tak	-	-
logo	string	Tak	-	One emoji from the curated icon set
crafterName	string	Tak	-	-
crafterAvatarSeed	string	Tak	-	-
background	Background	Tak	-	A preset background id for the workshop's poster. The id → CSS mapping is owned by the frontend.
customBackground	WorkshopCustomBackground	Nie	-	A freeform solid or gradient background overriding the preset `background` id, or null for no override.
titleFont	TitleFont	Tak	-	A preset title font id for the workshop's poster. The id → font mapping is owned by the frontend.
accentColor	HexColor \| null	Nie	-	-
plan	WorkshopPlan	Tak	-	The workshop's resolved plan; an expired time-boxed Pro reads back as free.
planExpiresAt	string \| null	Nie	-	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	Nie	-	-
context	WorkshopContext	Nie	-	The workshop's context notes as stored: free text describing the workshop and the moment the server last saved them.
contextDerived	WorkshopContextDerived	Nie	-	The AI-synthesized summary and suggested intents distilled from the workshop's context notes.
isDefault	boolean	Tak	-	-
members	array of WorkshopMember	Tak	-	-
createdAt	string	Tak	`format: "date-time"`	-

Przykład

{
  "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
Wspólna treść błędu walidacji, zobacz Błędy walidacji.
401Not authenticated
Brak treści.
403Forbidden
Brak treści.
404Not found
Brak treści.

Przykładowe żądanie

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}/contextexperimentalWymagana sesja

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.

Parametry ścieżki

Nazwa	Typ	Wymagane	Ograniczenia	Opis
workshopId	string	Tak	-	Workshop id

Treść żądania

Pole	Typ	Wymagane	Ograniczenia	Opis
notes	string	Tak	`maxLength: 4000`	Free-text notes about the workshop, trimmed, at most 4000 UTF-16 code units

Przykład

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

Odpowiedzi

200Success

Pole	Typ	Wymagane	Ograniczenia	Opis
notes	string	Tak	-	-
updatedAt	string	Tak	`format: "date-time"`	-

Przykład

{
  "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
Wspólna treść błędu walidacji, zobacz Błędy walidacji.
401Not authenticated
Brak treści.
403Forbidden
Brak treści.
404Not found
Brak treści.

Przykładowe żądanie

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}/entitlementsexperimentalWymagana sesja

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.

Parametry ścieżki

Nazwa	Typ	Wymagane	Ograniczenia	Opis
workshopId	string	Tak	-	Workshop id

Odpowiedzi

200Success

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

Przykład

{
  "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
Brak treści.
403Forbidden
Brak treści.
404Not found
Brak treści.

Przykładowe żądanie

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