Makr3D Public API / v1

Build 3D-print fulfilment into your store or workflow.

The Makr3D API lets sellers manage parts and products, request fulfilment quotes, create and track orders, and receive signed webhook events from the UK print hub.

OpenAPIDownload YAMLImport the OpenAPI 3.1 contract into Postman, Insomnia, RapidAPI or client-codegen tools.OverviewHelp centre pageA non-technical API and webhook summary for sellers and partners.TermsAPI acceptable useAuthentication, usage and integration expectations for API users.

Quick start

Create an API key in the seller dashboard under Settings, API keys. The raw key is shown once, starts with m3d_live_, and must be sent as a bearer token.

Every key is scoped to exactly one seller account. Do not send a seller id in requests; Makr3D derives tenant scope from the key.

curl -sS https://makr3d.app/api/v1/account \
  -H "Authorization: Bearer m3d_live_xxx"

Authentication

Use Authorization: Bearer m3d_live_xxx. Missing or invalid keys return 401 unauthorized; valid keys without the required scope return 403 forbidden.

Rate limits

MVP defaults are 60 requests/minute globally, 300 order creates/hour and 100 quote creates/hour per key. A 429 includes retry_after_seconds and a Retry-After header.

Versioning

The base path is https://makr3d.app/api/v1. Breaking changes ship as a new /api/v2; v1 receives only backwards-compatible additions.

Endpoint map

System

Scope: any valid key

Method	Path	Use
GET	/health	Authenticated liveness check for the API surface.
GET	/account	Read the seller account bound to the API key.

Parts

Scope: parts:read, parts:write

Method	Path	Use
GET	/parts	List the seller-owned printable parts.
POST	/parts	Create a draft part.
GET	/parts/{part_id}	Read one part and its print options.
PATCH	/parts/{part_id}	Update part metadata.
POST	/parts/{part_id}/files/upload-url	Upload an STL, 3MF, STEP or archive as multipart form data.
POST	/parts/{part_id}/submit-for-review	Submit a part for Makr3D review.
POST	/parts/{part_id}/sample-order	Order a sample print for a part.

Products

Scope: products:read, products:write

Method	Path	Use
GET	/products	List product groups.
POST	/products	Create a product group from parts.
GET	/products/{product_id}	Read a product group and its members.
PATCH	/products/{product_id}	Update product group fields.
POST	/products/{product_id}/parts	Add a part to a product group.
POST	/products/{product_id}/parts/reorder	Reorder product group members.
POST	/products/{product_id}/share	Enable revenue sharing for a product.

Quotes

Scope: quotes:read, quotes:write

Method	Path	Use
POST	/quotes	Create an idempotent fulfilment quote.
GET	/quotes/{quote_id}	Read a priced quote snapshot.

Orders

Scope: orders:read, orders:write

Method	Path	Use
GET	/orders	List orders with cursor pagination.
POST	/orders	Create an idempotent fulfilment order.
GET	/orders/{order_id}	Read an order with line items and shipment data.
GET	/orders/{order_id}/tracking	Read shipment/tracking details.
POST	/orders/{order_id}/cancel	Idempotently cancel an order where allowed.

Materials

Scope: any valid key

Method	Path	Use
GET	/materials	List printable materials and colours available for quoting.

Webhooks

Scope: webhooks:read, webhooks:write

Method	Path	Use
GET	/webhook-endpoints	List registered webhook endpoints.
POST	/webhook-endpoints	Create an idempotent webhook endpoint.
PATCH	/webhook-endpoints/{endpoint_id}	Update endpoint URL, events or status.
DELETE	/webhook-endpoints/{endpoint_id}	Remove an endpoint.
GET	/webhook-deliveries	List webhook delivery attempts.
GET	/webhook-deliveries/{delivery_id}	Inspect one delivery attempt.
POST	/webhook-deliveries/{delivery_id}/retry	Retry a failed delivery.

Idempotent writes

Money-adjacent writes require an Idempotency-Keyheader. Replaying the same key with the same body returns the stored response; replaying it with a different body returns idempotency_conflict.

Required on POST /orders, POST /quotes, POST /orders/{order_id}/cancel and POST /webhook-endpoints.

curl -sS https://makr3d.app/api/v1/quotes \
  -X POST \
  -H "Authorization: Bearer m3d_live_xxx" \
  -H "Idempotency-Key: quote_01HX..." \
  -H "Content-Type: application/json" \
  -d '{"part_id":"part_...","quantity":1}'

Webhooks

Register an HTTPS endpoint to receive signed events. Each delivery includes Makr3D-Event-Id, Makr3D-Event-Type, Makr3D-Timestamp and Makr3D-Signature.

order lifecycle changes
quote result updates
QA outcomes
product sharing changes
shop sales
billing charge outcomes
channel listing imports

const expected = hmacSha256(
  webhookSecret,
  `${timestamp}.${rawBody}`
)

// Header format:
// Makr3D-Signature: v1=<hex>

Errors

Every failure returns the same envelope with a stable code, human message and request id for support correlation. Some responses add structured details or retry timing.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "request_id": "req_...",
    "retry_after_seconds": 30
  }
}