# Supported formats & upload limits

The machine-readable source of truth is
[`/api/public/v1/capabilities`](/api/public/v1/capabilities) — agents
should read that endpoint before every upload rather than hardcoding any
value below. If this page and the capabilities feed disagree, the feed
wins.

## Product rule

**Every model format accepted for upload by maichine must be eligible to
enter the Production workflow. Preview-only model uploads are not
supported.**

An agent must never upload a preview-only file as a project version or
as a "color reference" fallback — the same Production-eligible artifact
that a user reviews in the preview is what enters production.

## Currently accepted upload formats

| Extension | Upload | Production | Notes |
|-----------|:------:|:----------:|-------|
| `.stl`    | ✅ | ✅ | Single-color printable. Binary or ASCII STL accepted. |
| `.3mf`    | ✅ | ✅ | Preferred for multi-color / multi-part models. |

## Upload limits

- **Max file size:** 25 MB per upload, on every path (browser, REST, MCP).
- **Daily quota per account:** up to 200 uploads and 500 MB combined.
- Uploads that exceed the limit fail with a structured error and the
  version is not persisted.

## Rejected formats

New uploads in any other format are rejected with the stable error
contract:

```json
{
  "error": "This format is not supported for Production.",
  "code": "FORMAT_NOT_PRODUCTION_SUPPORTED",
  "details": { "format": "glb" },
  "action_url": "/docs/supported-formats"
}
```

This applies to `.glb`, `.obj`, `.ply`, `.fbx`, and any other format not
listed in the capabilities feed's `formats.upload`.

## Legacy viewer-only support

Historical project versions previously uploaded in `.obj`, `.glb`,
`.ply`, or `.fbx` can still render read-only in the preview so a human
can inspect them, but:

- they are labeled *Legacy preview-only — not eligible for Production*,
- they cannot be selected as the Production version in the configurator,
- they do not displace a newer or older Production-eligible version as
  the project's "current" production candidate, and
- **no new upload in one of these formats is accepted, ever.**

## 3MF safety limits

`.3mf` archives are parsed defensively. An upload is rejected if it
exceeds any of:

- 250 MB extracted
- 100:1 compression ratio
- 200 zip entries
- 5,000 objects
- 5,000,000 triangles
- 32 texture files or 20 MB total texture bytes

`DOCTYPE`, `ENTITY`, and external DTD references (`SYSTEM` / `PUBLIC`)
are refused before parsing. Paths that escape the archive root (`..`,
absolute paths, drive letters) are refused. A spec-conformant 3MF core
namespace (`xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02"`)
and standard OPC relationship type URIs are accepted — they are part of
the specification, not an XXE vector.

## Guidance for agents

- Fetch `/api/public/v1/capabilities` at the start of every task and
  again before export; export directly into a format listed under
  `formats.upload`.
- Prefer `.3mf` whenever the model has more than one color or logical
  part.
- Use `.stl` for simple single-color geometry.
- If your tools cannot produce a Production-eligible artifact, **stop
  and report the concrete export blocker.** Never upload a preview-only
  format as a fallback and never present a preview-only file as a
  finished maichine version.
- If two attempts fail with the same format or compatibility cause,
  stop and report a platform issue rather than inventing more
  proprietary file variants.