Documentation

Complete Guide

Everything you need to integrate with MatterCloud — from your first API key to production webhooks.

Machine-readable spec: https://api.mattercloud.io/openapi.json

Overview

MatterCloud is a 3D printing service built for AI agents. The entire flow — from file upload to shipped part — runs through a REST API that agents can execute autonomously or with human approval.

Base URL

https://api.mattercloud.io

Core flow

Connect

Create account + get API key

Upload

Presign → PUT file → Confirm → Poll until ready

Quote

Select material, get pricing + confidence

Checkout

Create Stripe session or autonomous order

Track

Poll status or receive webhooks

Authentication

All authenticated endpoints require a Bearer token. API keys use the format mc_live_* and are shown once at creation. Only a SHA-256 hash is stored server-side.

Authorization: Bearer mc_live_xxxxxxxxxxxx

Connect

Create an account and receive a one-time API key. If the email already exists, a new key is issued for the existing account.

POST/v1/connect

curl -X POST https://api.mattercloud.io/v1/connect \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "my-agent"
  }'

Response

{
  "account_id": "uuid",
  "email": "[email protected]",
  "api_key_id": "uuid",
  "api_key": "mc_live_xxxxxxxxxxxx",
  "message": "Store this key now. It will not be shown again."
}

Material Catalog

Retrieve all available materials, processes, and pricing info. No authentication required. The response also tells your agent what inputs are needed before quoting.

GET/v1/catalog

curl https://api.mattercloud.io/v1/catalog

Response includes

{
  "items": [
    {
      "id": "sla_white",
      "process": "SLA",
      "material": "Photosensitive Resin White",
      "density_g_cm3": 1.12,
      "base_rate_per_g": 0.3,
      "minimum_fee_cents": 5000,
      "lead_time_min_days": 3,
      "lead_time_max_days": 6
    },
    ...
  ],
  "required_user_inputs": [
    "material_id", "quantity",
    "ship_country", "shipping_address_json"
  ],
  "supported_execution_modes": [
    "agent_assisted", "agent_autonomous", "human_manual"
  ]
}

Available processes

SLA

White Resin, Transparent, Full-color, Engineering, High-temp

SLS

Nylon Gufeng White, HP Black, Imported Nylon 11

SLM

Stainless Steel, Titanium Alloy

FDM

PLA, ABS

File Upload

Upload is a 3-step process: get a presigned URL, PUT the file directly to cloud storage, then confirm to trigger analysis. Files go directly to storage — they never pass through our API server.

Step 1 — Get presigned URL

POST/v1/files/presignAUTH

curl -X POST https://api.mattercloud.io/v1/files/presign \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "part.stl",
    "content_type": "model/stl",
    "size_bytes": 120312
  }'

Response

{
  "file_id": "uuid",
  "upload_url": "https://oss-signed-url...",
  "required_headers": { "Content-Type": "model/stl" },
  "next_action": "upload_file_then_confirm"
}

Step 2 — Upload the file

PUT{upload_url}

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: model/stl" \
  --data-binary @part.stl

Step 3 — Confirm upload

POST/v1/files/confirmAUTH

curl -X POST https://api.mattercloud.io/v1/files/confirm \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "file_id": "FILE_ID" }'

This enqueues background analysis. The file status moves to processing.

File Analysis

After confirmation, our worker analyzes the mesh using trimesh. Poll the file endpoint until status is ready or failed.

GET/v1/files/{file_id}AUTH

curl https://api.mattercloud.io/v1/files/FILE_ID \
  -H "Authorization: Bearer mc_live_xxx"

When ready

{
  "id": "uuid",
  "status": "ready",
  "metrics_json": {
    "bbox_mm": [45.2, 30.1, 12.8],
    "volume_cm3": 8.34,
    "surface_area_cm2": 42.1,
    "is_watertight": true,
    "is_manifold": true,
    "detected_unit": "mm",
    "unit_confidence": 0.95,
    "warnings": []
  }
}

File statuses

pending_upload — Presigned URL created, awaiting upload

processing — Upload confirmed, analysis running

ready — Analysis complete, can quote

failed — Analysis failed (check metrics_json for errors)

Possible warnings

non_watertight — Mesh has holes, may cause print issues

non_manifold — Inconsistent winding, geometry errors

too_large — Exceeds 440mm on any axis

Unit Override

STL files don't encode units. We auto-detect (mm, cm, or inches) based on bounding box heuristics, but agents or users can override. Overriding recomputes all metrics.

POST/v1/files/{file_id}/unitAUTH

curl -X POST https://api.mattercloud.io/v1/files/FILE_ID/unit \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "selected_unit": "mm",
    "confirmed_by": "user"
  }'

selected_unit: mm, cm, or in. confirmed_by: agent or user.

Quoting

Generate an instant price estimate for your file. The response includes a price range, confidence score, risk flags, lead time, and policy evaluation for execution mode.

POST/v1/quotesAUTH

curl -X POST https://api.mattercloud.io/v1/quotes \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "FILE_ID",
    "material_id": "sla_white",
    "quantity": 1,
    "ship_country": "US",
    "requested_execution_mode": "agent_assisted"
  }'

Response

{
  "quote_id": "uuid",
  "price_estimate": {
    "min": 5000,
    "max": 7500,
    "currency": "CNY"
  },
  "price_estimate_display": {
    "min_major": 50.0,
    "max_major": 75.0,
    "currency": "CNY"
  },
  "lead_time_days": { "min": 3, "max": 6 },
  "execution_confidence": 0.92,
  "risk_flags": [],
  "suggestions": [],
  "resolved_execution_mode": "agent_assisted",
  "requires_user_confirmation": true,
  "next_action": "create_checkout_session",
  "settings_url": "https://mattercloud.io/settings/TOKEN"
}

Execution modes

agent_assisted

Agent runs the flow, user approves payment via Stripe checkout link

agent_autonomous

Agent handles everything including payment (requires autopay + spending limits)

human_manual

User does everything through the web UI

Checkout

Create a Stripe checkout session for human-approved payment. Requires an Idempotency-Key header to prevent duplicate orders. Returns an approval URL the user opens in their browser.

POST/v1/checkout_sessionsAUTH

curl -X POST https://api.mattercloud.io/v1/checkout_sessions \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-here" \
  -d '{
    "quote_id": "QUOTE_ID",
    "shipping_address_json": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }'

Response

{
  "order_id": "uuid",
  "public_order_id": "mc_ord_xxxxxxxxxxxx",
  "approval_url": "https://checkout.stripe.com/...",
  "tracking_url": "https://mattercloud.io/orders/mc_ord_xxx",
  "review_url": "https://mattercloud.io/review/TOKEN",
  "status": "requires_payment",
  "next_action": "redirect_user_to_approval_url"
}

Required shipping fields

line1 — Street address (required)

city — City (required)

country — ISO 2-letter country code (required)

state, postal_code, line2 — Optional but recommended

Autonomous Orders

When the account has autopay enabled with sufficient spending limits, agents can place orders without a Stripe redirect. The charge is processed automatically against the saved payment method.

POST/v1/autonomous/ordersAUTH

curl -X POST https://api.mattercloud.io/v1/autonomous/orders \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "QUOTE_ID",
    "shipping_address_json": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }'

Requirements

Autopay enabled on account

Saved default payment method

Order amount within per-order cap

Monthly spend within monthly cap

Unit confidence above threshold (default 0.7)

Order Status

Check order status after checkout. Also available as a public endpoint without authentication.

GET/v1/orders/{order_id}AUTH

curl https://api.mattercloud.io/v1/orders/ORDER_ID \
  -H "Authorization: Bearer mc_live_xxx"

Order statuses

requires_payment — Checkout created, awaiting payment

paid — Payment confirmed

queued — In production queue

in_production — Currently printing

shipped — Out for delivery

delivered — Arrived

cancelled / refunded

Public Tracking

Every order gets an unguessable public ID. Anyone with the link can view status — no login required.

GET/v1/public/orders/{public_order_id}

curl https://api.mattercloud.io/v1/public/orders/mc_ord_xxxxxxxxxxxx

Web page: https://mattercloud.io/orders/mc_ord_xxxxxxxxxxxx

Webhooks

Register HTTPS endpoints to receive real-time order updates. Payloads are signed with HMAC-SHA256 so you can verify authenticity. The secret is shown once at creation.

POST/v1/webhooks/endpointsAUTH

curl -X POST https://api.mattercloud.io/v1/webhooks/endpoints \
  -H "Authorization: Bearer mc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook" }'

Response

{
  "id": "uuid",
  "url": "https://your-server.com/webhook",
  "secret": "base64-secret-shown-once"
}

Events

order.paid — Payment confirmed

order.status_changed — Any status transition

order.shipped — Tracking number assigned

Signature verification

Each delivery includes these headers:

X-Webhook-Timestamp: 1709123456
X-Webhook-Signature-256: sha256=abc123...
X-Webhook-Event: order.paid

Verify: HMAC-SHA256(secret, "{timestamp}.{body}")

Account Settings

Manage autopay settings and spending limits. Available both via authenticated API and via a signed link (for sharing with users who don't have the API key).

GET/v1/settingsAUTH

Returns current policy, monthly spend, and payment method status.

POST/v1/settings/autopayAUTH

{
  "autopay_enabled": true,
  "max_per_order_cents": 50000,
  "monthly_cap_cents": 200000
}

Signed settings link

The quote response includes a settings_url — a time-limited link (24h default) that lets users manage autopay without needing the API key. Shareable via chat, email, etc.

Payment Methods

For autonomous orders, a saved payment method is required. Use Stripe SetupIntents to securely vault a card.

POST/v1/payments/setup_intentAUTH

Creates a Stripe SetupIntent. Returns client_secret for completing card setup on the frontend.

POST/v1/payments/default_methodAUTH

{ "payment_method_id": "pm_xxxx" }

Set the default payment method for autonomous charges.

Error Handling

All errors return JSON with an error field. HTTP status codes follow standard conventions.

// 400 Bad Request
{ "error": "file_not_ready" }

// 401 Unauthorized
{ "error": "invalid_api_key" }

// 404 Not Found
{ "error": "file_not_found" }

// 429 Too Many Requests
{ "error": "rate_limit_exceeded" }

// 503 Service Unavailable
{ "error": "upstream_temporarily_unavailable" }

Common error codes

file_not_found — File ID doesn't exist or belongs to another account

file_not_ready — File analysis isn't complete yet

unknown_material — Invalid material_id

quote_not_found / quote_expired — Quote ID invalid or timed out

missing_shipping_fields — Required address fields absent

autonomous_not_allowed — Policy check failed for autopay

invalid_token / token_expired — Signed link is invalid or expired

Rate Limits

60 requests per minute per API key. Rate limit headers are included on every response.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709123516

Agent Policy

AI agents should follow the MatterCloud agent policy for safe, structured execution. The policy defines behavior rules, state persistence, question prompts, and failure handling.

Non-negotiable rules

1. Never proceed to payment without explicit user approval

2. Ask follow-up questions when required inputs are missing or ambiguous

3. Persist run state and resume from last successful step

4. Surface risks, confidence, and warnings before asking approval

5. On failure, report the exact failed step and recover without restarting

When to ask the user

Material choice, quantity, or ship country is unknown

Shipping address is missing required fields

Risk flags include non_watertight, non_manifold, or too_large

Execution confidence is below 0.75

State to persist across turns

account_id, api_key_id, file_id, quote_id,
order_id, public_order_id, selected_material_id,
quantity, ship_country, last_known_status

Full policy document

Available at https://api.mattercloud.io/v1/agent-policy

Ready to integrate?

Create your account and start building.

Get API Key