Public REST API

The REST API the Mercastra app itself uses, described from the API contract at build time. Endpoint summaries, descriptions and field descriptions come from that contract and are in English only.

API version0.20.0Base URLhttps://mercastra.cloud/apiopenapi.jsonEnglish only

Authentication

Requests authenticate with the session cookie the app sets at sign-in. Every request other than a GET must also send the X-CSRF-Token header, echoing the value of the csrf-token cookie.

There is no API key or token for third-party integrations yet.

Stability

Each endpoint carries one of two stability levels.

experimental
May change without notice.
stable
Stays as documented.

Endpoints

Every public endpoint, in path order. Each one links to its full description on its resource's page.

  1. post/authenticateSign in with email and password
  2. get/estimates/{estimateId}Read an estimate
  3. patch/estimates/{estimateId}Update an estimate's name, recipient, markup or discount
  4. delete/estimates/{estimateId}Delete an estimate
  5. post/estimates/{estimateId}/confirmSnapshot an estimate's current content as a new revision
  6. post/estimates/{estimateId}/duplicateDuplicate an estimate
  7. get/estimates/{estimateId}/handoffsList an estimate's hand-offs
  8. post/estimates/{estimateId}/handoffsRecord that an estimate was handed off to its recipient
  9. post/estimates/{estimateId}/line-itemsAdd a line item to an estimate
  10. patch/estimates/{estimateId}/line-items/{lineItemId}Update a line item
  11. delete/estimates/{estimateId}/line-items/{lineItemId}Remove a line item
  12. get/estimates/{estimateId}/pdf-exportsList an estimate's PDF exports
  13. post/estimates/{estimateId}/pdf-exportsGenerate a PDF export of an estimate
  14. get/estimates/{estimateId}/pdf-exports/{pdfExportId}Download a PDF export's bytes
  15. delete/estimates/{estimateId}/pdf-exports/{pdfExportId}Delete a PDF export
  16. get/estimates/{estimateId}/revisionsList an estimate's revisions
  17. get/filesList files in a category and scope
  18. post/filesUpload a file
  19. get/files/{fileId}Download a file's bytes
  20. get/grids/{gridId}Read a grid
  21. patch/grids/{gridId}Rename a grid or change its icon size
  22. delete/grids/{gridId}Delete a grid
  23. post/grids/{gridId}/buttonsAdd a button to a grid
  24. patch/grids/{gridId}/buttons/{buttonId}Update a button
  25. delete/grids/{gridId}/buttons/{buttonId}Remove a button
  26. post/grids/{gridId}/duplicateDuplicate a grid
  27. post/logoutEnd the caller's session
  28. get/meRead the signed-in account's profile
  29. patch/meUpdate the signed-in account's profile
  30. get/me/data-exportExport everything stored about the account
  31. get/orders/{orderId}Read an order
  32. patch/orders/{orderId}Update an order's title, customer name or notes
  33. patch/orders/{orderId}/statusChange an order's status
  34. get/predefined-itemsList the catalog of predefined grid items, domains and templates
  35. get/workshopsList the caller's workshops
  36. patch/workshops/{workshopId}Update the workshop's profile
  37. put/workshops/{workshopId}/contextReplace the workshop's context notes
  38. get/workshops/{workshopId}/entitlementsRead the workshop's plan entitlements and quota usage
  39. get/workshops/{workshopId}/estimatesList a workshop's estimates
  40. post/workshops/{workshopId}/estimatesCreate an estimate in a workshop
  41. get/workshops/{workshopId}/estimates/most-used-line-itemsList the workshop's most-used line items
  42. delete/workshops/{workshopId}/grid-icons/{fileId}Delete a grid button icon
  43. get/workshops/{workshopId}/gridsList a workshop's grids
  44. post/workshops/{workshopId}/gridsCreate a grid in a workshop
  45. get/workshops/{workshopId}/ordersList a workshop's orders
  46. post/workshops/{workshopId}/ordersCreate an order in a workshop

Schemas

The named shapes a field's type links to: every entity and model, documented once on its own page.

Browse all schemas →

Validation errors

Every endpoint that validates its request body answers a 400 with the same shape.

Sent with status 400 when the request body does not match the endpoint's schema. Each issue names the offending path and says what is wrong with it.

FieldTypeRequiredConstraintsDescription
statusstringYesconst: "fail"-
messagearray of objectYes--
message[].patharray of string | numberYes--
message[].messagestringYes--