openapi: 3.0.3
info:
  title: zrender API
  version: "1.0.0"
  description: |
    Fast 3D/CAD processing. Send a 3D file (STL, GLB/glTF, OBJ, 3MF, PLY,
    STEP, IGES) and get an engineering-style PNG (a single view, a 2x2
    four-view sheet, or a turntable as animated PNG or GIF), a converted model
    (GLB, STL, OBJ, PLY, 3MF), a 2D line drawing (SVG, DXF) or measurements
    (size, area, volume, watertightness, overhangs; CAD parts and assembly tree).

    "zrender" is a working name.

    Data retention: input files are held only for the duration of the render
    and then deleted. Rendered outputs are cached for at most 30 days (keyed
    by a hash of the file and parameters). Logs are kept at most 30 days and
    never contain file contents.

    Limits: input 100 MB; 5,000,000 triangles; output 2048 px per side;
    10 s per render.

    Units charged per request (DRAFT): still, sheet, conversion, drawing or
    analysis 1 (quote data included), turntable 4; STEP and IGES input multiply by 3.
servers:
  - url: https://api.example.com
    description: Production (placeholder domain)
  - url: http://localhost:8787
    description: Local development
tags:
  - name: render
    description: Render a 3D file to PNG
  - name: demo
    description: Key-less demo endpoint used by the website
  - name: account
    description: Plan and usage
  - name: process
    description: Convert, draw and measure models
  - name: jobs
    description: Asynchronous jobs, batches and webhooks

paths:
  /v1/convert:
    post:
      tags: [process]
      operationId: convert
      summary: Convert a model to GLB, STL, OBJ, PLY or 3MF
      description: GLB is Y-up in metres, STL/3MF Z-up and OBJ/PLY Y-up in millimetres. 1 unit (STEP/IGES input x3).
      security:
        - bearerAuth: []
      parameters:
        - { name: to, in: query, required: true, schema: { type: string, enum: [glb, stl, obj, ply, 3mf] } }
        - { name: quantize, in: query, description: "GLB: KHR_mesh_quantization", schema: { type: integer, enum: [0, 1], default: 0 } }
        - { name: simplify, in: query, description: "At most this many triangles (vertex clustering)", schema: { type: integer, minimum: 4 } }
        - { name: repair, in: query, schema: { type: integer, enum: [0, 1], default: 0 } }
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/filename"
      requestBody:
        $ref: "#/components/requestBodies/ModelFile"
      responses:
        "200":
          description: The converted model.
          content:
            model/gltf-binary: { schema: { type: string, format: binary } }
            model/stl: { schema: { type: string, format: binary } }
            model/obj: { schema: { type: string } }
            model/3mf: { schema: { type: string, format: binary } }
            application/octet-stream: { schema: { type: string, format: binary } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/QuotaExceeded" }
        "415": { $ref: "#/components/responses/UnsupportedFormat" }
        "422": { $ref: "#/components/responses/InvalidModel" }
  /v1/drawing:
    post:
      tags: [process]
      operationId: drawing
      summary: 2D line drawing (SVG or DXF) with hidden lines
      description: Orthographic and true to scale; `sheet=1` is a third-angle layout of front, top, right and isometric views. 1 unit (STEP/IGES input x3).
      security:
        - bearerAuth: []
      parameters:
        - { name: format, in: query, schema: { type: string, enum: [svg, dxf], default: svg } }
        - { name: view, in: query, schema: { type: string, enum: [front, back, left, right, top, bottom, iso], default: front } }
        - $ref: "#/components/parameters/sheet"
        - { name: hidden, in: query, description: "0 leaves hidden lines out", schema: { type: integer, enum: [0, 1], default: 1 } }
        - $ref: "#/components/parameters/azimuth"
        - $ref: "#/components/parameters/elevation"
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/filename"
      requestBody:
        $ref: "#/components/requestBodies/ModelFile"
      responses:
        "200":
          description: The drawing.
          content:
            image/svg+xml: { schema: { type: string } }
            image/vnd.dxf: { schema: { type: string } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/InvalidModel" }
  /v1/analyze:
    post:
      tags: [process]
      operationId: analyze
      summary: Size, area, volume, watertightness, overhangs; CAD parts, features and assembly tree; FDM print estimate; DXF cut metrics
      description: "`csv=1` returns a bill of materials as CSV. `print=1` adds an FDM print estimate (time, filament, supports). DXF input adds cut metrics. 1 unit (STEP/IGES input x3)."
      security:
        - bearerAuth: []
      parameters:
        - { name: density, in: query, description: "g/cm3; adds mass_g", schema: { type: number, minimum: 0.0001, maximum: 100 } }
        - { name: printer, in: query, description: "Build volume XxYxZ in mm; adds printer.fits", schema: { type: string, example: 256x256x256 } }
        - { name: overhang_angle, in: query, schema: { type: number, minimum: 0, maximum: 90, default: 45 } }
        - { name: repair, in: query, schema: { type: integer, enum: [0, 1], default: 0 } }
        - { name: print, in: query, description: "1 adds the FDM print estimate (print)", schema: { type: integer, enum: [0, 1], default: 0 } }
        - { name: print_settings, in: query, description: "key=value pairs, comma-separated, named as in print.settings (implies print=1)", schema: { type: string, example: "layer_height=0.28,infill=0.2,supports=true" } }
        - { name: material, in: query, description: "Filament density preset (implies print=1)", schema: { type: string, enum: [pla, petg, abs, asa, tpu, pa, pc] } }
        - { name: thickness, in: query, description: "DXF: sheet thickness in mm (volume, mass; also the plate for render/convert)", schema: { type: number, minimum: 0.001, maximum: 10000 } }
        - { name: cut_speed, in: query, description: "DXF: cutting speed in mm/min; adds cut.cut_time_s", schema: { type: number, minimum: 0.001 } }
        - { name: pierce_time, in: query, description: "DXF: seconds per pierce", schema: { type: number, minimum: 0, maximum: 3600, default: 0.5 } }
        - { name: csv, in: query, schema: { type: integer, enum: [0, 1], default: 0 } }
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/filename"
      requestBody:
        $ref: "#/components/requestBodies/ModelFile"
      responses:
        "200":
          description: The measurements.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Analysis" }
            text/csv: { schema: { type: string } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/InvalidModel" }
  /v1/watches:
    get:
      tags: [jobs]
      operationId: listWatches
      summary: Watched buckets of this account
      security:
        - bearerAuth: []
      responses:
        "200":
          description: "{ watches: [Watch] }"
    post:
      tags: [jobs]
      operationId: createWatch
      summary: Watch an S3-compatible bucket and process every new model
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [endpoint, bucket, access_key_id, secret_access_key, input_prefix, output_prefix]
              properties:
                name: { type: string }
                endpoint: { type: string, example: "https://account.r2.cloudflarestorage.com" }
                region: { type: string, default: us-east-1 }
                bucket: { type: string }
                access_key_id: { type: string }
                secret_access_key: { type: string, description: "Stored encrypted; never returned." }
                input_prefix: { type: string, example: "incoming/" }
                output_prefix: { type: string, example: "previews/" }
                op: { type: string, enum: [render, convert, drawing, analyze], default: render }
                params: { type: object, description: "The operation's query parameters", example: { size: 512, sheet: 1 } }
                interval_s: { type: integer, minimum: 60, maximum: 86400, default: 300 }
                callback_url: { type: string, format: uri }
      responses:
        "201":
          description: The watch.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Watch" }
        "400": { $ref: "#/components/responses/BadRequest" }
  /v1/watches/{id}:
    get:
      tags: [jobs]
      operationId: getWatch
      summary: One watched bucket
      security:
        - bearerAuth: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The watch.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Watch" }
        "404": { description: "No such watch (or another account's)." }
    delete:
      tags: [jobs]
      operationId: deleteWatch
      summary: Stop watching and forget the credentials
      security:
        - bearerAuth: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: Deleted. }
  /v1/watches/{id}/{action}:
    post:
      tags: [jobs]
      operationId: watchAction
      summary: "pause, resume, or run now (run?wait=1 returns the pass result)"
      security:
        - bearerAuth: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        - { name: action, in: path, required: true, schema: { type: string, enum: [pause, resume, run] } }
        - { name: wait, in: query, schema: { type: integer, enum: [0, 1] } }
      responses:
        "200": { description: The watch (with `pass` for run?wait=1). }
        "202": { description: The pass was started. }
        "409": { description: The watch is paused. }
  /v1/batch:
    post:
      tags: [jobs]
      operationId: submitBatch
      summary: Process every model in a ZIP as one job
      description: At most 100 model files (100 MB each, 400 MB in total). The result is a ZIP with one output per input and manifest.json. Failed files are not charged.
      security:
        - bearerAuth: []
      parameters:
        - { name: op, in: query, schema: { type: string, enum: [render, convert, drawing, analyze], default: render } }
        - $ref: "#/components/parameters/callback_url"
      requestBody:
        content:
          application/zip:
            schema: { type: string, format: binary }
      responses:
        "202":
          description: Accepted. Poll `status_url` (or wait for the webhook).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Job" }
        "402": { description: "`quota_exceeded`: the batch could cost more than is left." }
        "422": { description: "Not a ZIP, no model files, or over the limits." }
  /v1/render:
    post:
      tags: [render]
      operationId: renderUpload
      summary: Render an uploaded file
      description: |
        The body is the file: either the raw bytes
        (`Content-Type: application/octet-stream`) or `multipart/form-data`
        with one field named `file`. Render parameters go in the query
        string. The optional `filename` query parameter (or the multipart
        filename) is used only as a format hint.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/filename"
        - $ref: "#/components/parameters/view"
        - $ref: "#/components/parameters/size"
        - $ref: "#/components/parameters/width"
        - $ref: "#/components/parameters/height"
        - $ref: "#/components/parameters/bg"
        - $ref: "#/components/parameters/transparent"
        - $ref: "#/components/parameters/edges"
        - $ref: "#/components/parameters/edge_width"
        - $ref: "#/components/parameters/shading"
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/color"
        - $ref: "#/components/parameters/sheet"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/frames"
        - $ref: "#/components/parameters/margin"
      requestBody:
        $ref: "#/components/requestBodies/ModelFile"
      responses:
        "200":
          $ref: "#/components/responses/Image"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/QuotaExceeded"
        "413":
          $ref: "#/components/responses/TooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedFormat"
        "422":
          $ref: "#/components/responses/InvalidModel"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/Internal"
        "504":
          $ref: "#/components/responses/Timeout"
    get:
      tags: [render]
      operationId: renderUrl
      summary: Render a file fetched from a URL
      description: |
        Same as `POST /v1/render`, but the server fetches the file from `url`.
        http(s) only; private, loopback and link-local addresses are refused;
        100 MB cap; 10 s timeout.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/view"
        - $ref: "#/components/parameters/size"
        - $ref: "#/components/parameters/width"
        - $ref: "#/components/parameters/height"
        - $ref: "#/components/parameters/bg"
        - $ref: "#/components/parameters/transparent"
        - $ref: "#/components/parameters/edges"
        - $ref: "#/components/parameters/edge_width"
        - $ref: "#/components/parameters/shading"
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/color"
        - $ref: "#/components/parameters/sheet"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/frames"
        - $ref: "#/components/parameters/margin"
      responses:
        "200":
          $ref: "#/components/responses/Image"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/QuotaExceeded"
        "413":
          $ref: "#/components/responses/TooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedFormat"
        "422":
          $ref: "#/components/responses/InvalidModel"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/Internal"
        "502":
          $ref: "#/components/responses/FetchFailed"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/demo/render:
    post:
      tags: [demo]
      operationId: renderDemo
      summary: Render an uploaded file without a key (website demo)
      description: |
        No key. For the website demo (STEP in particular). Same body and
        parameters as `POST /v1/render`, with tighter limits: 20 MB input,
        output at most 512 px, no turntable, 10 renders per hour per IP.
      security: []
      parameters:
        - $ref: "#/components/parameters/filename"
        - $ref: "#/components/parameters/view"
        - name: size
          in: query
          description: Square output size in pixels (demo maximum 512). Or use `width` + `height`.
          schema:
            type: integer
            minimum: 16
            maximum: 512
            default: 512
        - name: width
          in: query
          description: Output width in pixels (demo maximum 512).
          schema:
            type: integer
            minimum: 16
            maximum: 512
            default: 512
        - name: height
          in: query
          description: Output height in pixels (demo maximum 512).
          schema:
            type: integer
            minimum: 16
            maximum: 512
            default: 512
        - $ref: "#/components/parameters/bg"
        - $ref: "#/components/parameters/transparent"
        - $ref: "#/components/parameters/edges"
        - $ref: "#/components/parameters/edge_width"
        - $ref: "#/components/parameters/shading"
        - $ref: "#/components/parameters/up"
        - $ref: "#/components/parameters/color"
        - $ref: "#/components/parameters/sheet"
        - name: format
          in: query
          description: Output format. The demo has no turntable, so only `png`.
          schema:
            type: string
            enum: [png]
            default: png
        - $ref: "#/components/parameters/margin"
      requestBody:
        $ref: "#/components/requestBodies/ModelFile"
      responses:
        "200":
          description: The rendered image.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            X-ZRender-Cache:
              $ref: "#/components/headers/X-ZRender-Cache"
            X-ZRender-Triangles:
              $ref: "#/components/headers/X-ZRender-Triangles"
            X-ZRender-Render-Ms:
              $ref: "#/components/headers/X-ZRender-Render-Ms"
          content:
            image/png:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "413":
          $ref: "#/components/responses/TooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedFormat"
        "422":
          $ref: "#/components/responses/InvalidModel"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/Internal"
        "504":
          $ref: "#/components/responses/Timeout"

  /v1/jobs:
    post:
      tags: [render]
      operationId: submitJob
      summary: Queue any operation for a large file (longer time and memory limits)
      description: Same body and parameters as `POST /v1/render`, or with `op=convert|drawing|analyze` as that endpoint. Up to 120 s and 8 GB per job; at most 3 queued or running jobs per account. Units are charged only when the job succeeds.
      security:
        - bearerAuth: []
      parameters:
        - { name: op, in: query, schema: { type: string, enum: [render, convert, drawing, analyze], default: render } }
        - $ref: "#/components/parameters/callback_url"
        - $ref: "#/components/parameters/view"
        - $ref: "#/components/parameters/size"
        - $ref: "#/components/parameters/sheet"
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/shading"
        - $ref: "#/components/parameters/up"
      requestBody:
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        "202":
          description: Accepted. Poll `status_url`.
          headers:
            Location: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Job" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { description: "`quota_exceeded` (queued jobs count)." }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { description: "`busy`: the job queue is full." }
  /v1/jobs/{id}:
    get:
      tags: [render]
      operationId: getJob
      summary: Job status
      security:
        - bearerAuth: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The job.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Job" }
        "404": { description: "No such job (or another account's)." }
  /v1/jobs/{id}/result:
    get:
      tags: [render]
      operationId: getJobResult
      summary: Output of a finished job (its type is the job's result_type)
      security:
        - bearerAuth: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The output (PNG, GIF, GLB, SVG, JSON, ZIP for batches, ...).
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "409": { description: "`job_not_finished` or `job_failed`." }
        "410": { description: "`gone`: the result has expired." }
  /v1/usage:
    get:
      tags: [account]
      operationId: getUsage
      summary: Plan and units used in the current period
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Usage for the current period.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Usage"
              example:
                plan: free
                period: "2026-11"
                units_used: 12
                units_included: 100
                hard_limit: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/Internal"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key as a bearer token: `Authorization: Bearer zr_live_…`."

  parameters:
    url:
      name: url
      in: query
      required: true
      description: |
        The file to fetch and render. http(s) only; private, loopback and
        link-local addresses are refused; 100 MB cap; 10 s timeout.
      schema:
        type: string
        format: uri
      example: https://example.com/models/gear.stl
    filename:
      name: filename
      in: query
      description: Used only as a format hint (the multipart filename works too).
      schema:
        type: string
      example: part.stl
    view:
      name: view
      in: query
      description: Camera.
      schema:
        type: string
        enum: [iso, front, back, left, right, top, bottom, persp]
        default: iso
    size:
      name: size
      in: query
      description: Square output size in pixels. Or use `width` + `height`.
      schema:
        type: integer
        minimum: 16
        maximum: 2048
        default: 512
    width:
      name: width
      in: query
      description: Output width in pixels.
      schema:
        type: integer
        minimum: 16
        maximum: 2048
        default: 512
    height:
      name: height
      in: query
      description: Output height in pixels.
      schema:
        type: integer
        minimum: 16
        maximum: 2048
        default: 512
    bg:
      name: bg
      in: query
      description: Background colour as `RRGGBB` (no `#`).
      schema:
        type: string
        pattern: "^[0-9A-Fa-f]{6}$"
        default: F4F5F7
    transparent:
      name: transparent
      in: query
      description: Transparent background (`0` or `1`).
      schema:
        type: integer
        enum: [0, 1]
        default: 0
    edges:
      name: edges
      in: query
      description: Feature lines (`0` or `1`).
      schema:
        type: integer
        enum: [0, 1]
        default: 1
    edge_width:
      name: edge_width
      in: query
      description: Line width in pixels.
      schema:
        type: number
        minimum: 0
        maximum: 8
        default: 1
    up:
      name: up
      in: query
      description: "Which axis points up. Default: the format's convention (STL, STEP, IGES, 3MF Z-up; glTF, OBJ, PLY Y-up)."
      schema:
        type: string
        enum: [y, z]
    shading:
      name: shading
      in: query
      description: "`auto`: smooth curved surfaces, edges sharper than 30 degrees stay hard. `smooth`: blend across every edge. `flat`: one shade per triangle. STEP input uses exact surface normals from the CAD model."
      schema:
        type: string
        enum: [auto, smooth, flat]
        default: auto
    color:
      name: color
      in: query
      description: Override the model colour, as `RRGGBB`. Default is the model's own colours.
      schema:
        type: string
        pattern: "^[0-9A-Fa-f]{6}$"
    sheet:
      name: sheet
      in: query
      description: "2x2 sheet: iso, front, right, top at a common scale (`0` or `1`)."
      schema:
        type: integer
        enum: [0, 1]
        default: 0
    format:
      name: format
      in: query
      description: Output format. `apng`, `gif` and `webm` (VP9 video) are turntable animations.
      schema:
        type: string
        enum: [png, apng, gif, webm]
        default: png
    frames:
      name: frames
      in: query
      description: Turntable frame count (`format=apng` or `gif`).
      schema:
        type: integer
        minimum: 8
        maximum: 72
        default: 36
    margin:
      name: margin
      in: query
      description: Empty border fraction.
      schema:
        type: number
        minimum: 0
        maximum: 0.45
        default: 0.06
    azimuth:
      name: azimuth
      in: query
      description: Custom camera, degrees around the vertical axis (0 = front). Overrides the view's.
      schema: { type: number, minimum: -3600, maximum: 3600 }
    elevation:
      name: elevation
      in: query
      description: Custom camera, degrees above the horizon.
      schema: { type: number, minimum: -90, maximum: 90 }
    callback_url:
      name: callback_url
      in: query
      description: "https URL that receives the job's status JSON when it finishes, signed with X-ZRender-Signature: t=<unix>,v1=<hex HMAC-SHA256 of '<t>.<body>'> (account webhook secret)."
      schema: { type: string, format: uri }

  requestBodies:
    ModelFile:
      required: true
      description: The 3D file (STL, GLB/glTF, OBJ, 3MF or STEP).
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary
        multipart/form-data:
          schema:
            type: object
            required: [file]
            properties:
              file:
                type: string
                format: binary
                description: The 3D file. Its filename is used only as a format hint.

  headers:
    X-Request-Id:
      description: Identifier of this request.
      schema:
        type: string
    X-ZRender-Cache:
      description: Whether the output came from the cache.
      schema:
        type: string
        enum: [hit, miss]
    X-ZRender-Triangles:
      description: Triangle count of the model.
      schema:
        type: integer
    X-ZRender-Render-Ms:
      description: Render time in milliseconds.
      schema:
        type: number
    X-ZRender-Units:
      description: "Units charged: still 1, sheet 1, turntable 4, STEP input x3."
      schema:
        type: integer
    X-ZRender-Quota-Remaining:
      description: Units remaining in the current period.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer

  responses:
    Image:
      description: The rendered image. `image/png` is also used for `apng` (animated PNG).
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
        X-ZRender-Cache:
          $ref: "#/components/headers/X-ZRender-Cache"
        X-ZRender-Triangles:
          $ref: "#/components/headers/X-ZRender-Triangles"
        X-ZRender-Render-Ms:
          $ref: "#/components/headers/X-ZRender-Render-Ms"
        X-ZRender-Units:
          $ref: "#/components/headers/X-ZRender-Units"
        X-ZRender-Quota-Remaining:
          $ref: "#/components/headers/X-ZRender-Quota-Remaining"
      content:
        image/png:
          schema:
            type: string
            format: binary
    BadRequest:
      description: "`bad_request`: bad or missing parameter, empty body."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: bad_request, message: "size must be between 16 and 2048", request_id: "req_0123456789" }
    Unauthorized:
      description: "`unauthorized`: missing or invalid key."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: unauthorized, message: "missing or invalid API key", request_id: "req_0123456789" }
    QuotaExceeded:
      description: "`quota_exceeded`: free tier used up (100 units/month)."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: quota_exceeded, message: "free tier used up (100 units/month)", request_id: "req_0123456789" }
    TooLarge:
      description: "`too_large`: input over 100 MB, or over 5,000,000 triangles."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: too_large, message: "input is larger than 100 MB", request_id: "req_0123456789" }
    UnsupportedFormat:
      description: "`unsupported_format`: unknown format, Draco/meshopt, STEP on a build without it."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: unsupported_format, message: "STEP is not available on this build", request_id: "req_0123456789" }
    InvalidModel:
      description: "`invalid_model`: corrupt or empty model."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: invalid_model, message: "the model contains no triangles", request_id: "req_0123456789" }
    RateLimited:
      description: "`rate_limited`: too many requests."
      headers:
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: rate_limited, message: "too many requests", request_id: "req_0123456789" }
    FetchFailed:
      description: "`fetch_failed`: `url=` could not be fetched or was refused."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: fetch_failed, message: "the URL could not be fetched", request_id: "req_0123456789" }
    Timeout:
      description: "`timeout`: render took longer than 10 s."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: timeout, message: "render took longer than 10 s", request_id: "req_0123456789" }
    Internal:
      description: "`internal`: anything else."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: { code: internal, message: "internal error", request_id: "req_0123456789" }

  schemas:
    Watch:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        endpoint: { type: string }
        region: { type: string }
        bucket: { type: string }
        input_prefix: { type: string }
        output_prefix: { type: string }
        access_key_id: { type: string }
        params: { type: object }
        interval_s: { type: integer }
        callback_url: { type: string, nullable: true }
        status: { type: string, enum: [active, paused] }
        last_run_at: { type: string, format: date-time, nullable: true }
        next_run_at: { type: string, format: date-time }
        last_error: { type: string, nullable: true }
        processed: { type: integer }
        failed: { type: integer }
    Analysis:
      type: object
      description: "Lengths in model units (units: mm, m or null). volume and center_of_mass only for watertight models."
      properties:
        triangles: { type: integer }
        points: { type: integer }
        up: { type: string, enum: [y, z] }
        units: { type: string, nullable: true }
        bbox:
          type: object
          properties:
            min: { type: array, items: { type: number } }
            max: { type: array, items: { type: number } }
            size: { type: array, items: { type: number } }
        surface_area: { type: number }
        volume: { type: number, nullable: true }
        volume_estimate: { type: number }
        center_of_mass: { type: array, items: { type: number } }
        mass_g: { type: number }
        watertight: { type: boolean }
        inward_normals: { type: boolean }
        components: { type: integer }
        boundary_edges: { type: integer }
        non_manifold_edges: { type: integer }
        flipped_edges: { type: integer }
        degenerate_triangles: { type: integer }
        duplicate_triangles: { type: integer }
        overhang: { type: object, properties: { angle_deg: { type: number }, area: { type: number } } }
        printer: { type: object, properties: { size: { type: array, items: { type: number } }, fits: { type: boolean }, fits_rotated: { type: boolean } } }
        cad:
          type: object
          description: STEP and IGES only.
          properties:
            units: { type: string }
            parts:
              type: array
              items:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }
                  quantity: { type: integer }
                  solids: { type: integer }
                  volume: { type: number }
                  surface_area: { type: number }
                  bbox_size: { type: array, items: { type: number } }
                  color: { type: string }
                  features: { $ref: "#/components/schemas/Features" }
            tree: { type: array, items: { type: object } }
            totals: { type: object }
        print: { $ref: "#/components/schemas/PrintEstimate" }
        print_profile: { type: string, enum: [file, default] }
        slicer:
          type: object
          description: 3MF projects from Bambu Studio, OrcaSlicer or PrusaSlicer.
          properties:
            application: { type: string }
            printer: { type: string }
            filament_type: { type: string }
            settings: { type: string, description: "The file's profile as print_settings" }
            plates:
              type: array
              items:
                type: object
                properties:
                  index: { type: integer }
                  time_s: { type: number }
                  weight_g: { type: number }
                  support_used: { type: boolean }
                  filaments: { type: array, items: { type: object } }
        cut:
          type: object
          description: DXF input only.
          properties:
            units: { type: string }
            size: { type: array, items: { type: number } }
            cut_length_mm: { type: number }
            pierces: { type: integer }
            contours: { type: object, properties: { closed: { type: integer }, open: { type: integer } } }
            parts: { type: integer }
            holes: { type: integer }
            net_area_mm2: { type: number }
            smallest_hole_mm: { type: number }
            thickness_mm: { type: number }
            volume_mm3: { type: number }
            mass_g: { type: number }
            cut_time_s: { type: number }
    Features:
      type: object
      description: Manufacturing features of a CAD part (exact B-rep geometry, part coordinates, mm).
      properties:
        faces: { type: object, additionalProperties: { type: integer } }
        hole_count: { type: integer }
        holes:
          type: array
          items:
            type: object
            properties:
              count: { type: integer }
              diameter: { type: number }
              depth: { type: number }
              through: { type: boolean }
              axis: { type: array, items: { type: number } }
              opens: { type: array, items: { type: number } }
              counterbore: { type: object, properties: { diameter: { type: number }, depth: { type: number } } }
              countersink: { type: object, properties: { diameter: { type: number }, angle: { type: number } } }
              drill_point_angle: { type: number }
              positions: { type: array, items: { type: array, items: { type: number } } }
        holes_axis_aligned: { type: boolean }
        internal_radii: { type: array, items: { type: number } }
        min_internal_radius: { type: number }
        stock: { type: object, properties: { size: { type: array, items: { type: number } }, volume: { type: number }, removal_volume: { type: number }, removal_ratio: { type: number } } }
        sheet_metal:
          type: object
          nullable: true
          properties:
            thickness: { type: number }
            bend_count: { type: integer }
            bends: { type: array, items: { type: object, properties: { inner_radius: { type: number }, angle: { type: number } } } }
            flat_area: { type: number }
    PrintEstimate:
      type: object
      description: FDM estimate from slicing the model (within about 5 % of PrusaSlicer with the same settings on most test parts).
      properties:
        technology: { type: string, enum: [fdm] }
        time_s: { type: number }
        layers: { type: integer }
        height_mm: { type: number }
        filament_mm: { type: number }
        filament_g: { type: number }
        model_volume_mm3: { type: number }
        extruded_mm3: { type: number }
        extruded: { type: object, additionalProperties: { type: number } }
        time: { type: object, additionalProperties: { type: number } }
        supported_area_mm2: { type: number }
        bridge_area_mm2: { type: number }
        settings: { type: object, additionalProperties: true }
    Job:
      type: object
      properties:
        id: { type: string, example: job_Zk3Pq9xY2bLm }
        status: { type: string, enum: [queued, running, done, failed] }
        op: { type: string, enum: [render, convert, drawing, analyze, batch] }
        result_type: { type: string, description: "Content type of the result (when done)." }
        files: { type: integer, description: "Batches: model files to process (on submit)." }
        format: { type: string, example: step }
        created_at: { type: string, format: date-time }
        started_at: { type: string, format: date-time, nullable: true }
        finished_at: { type: string, format: date-time, nullable: true }
        status_url: { type: string }
        result_url: { type: string, description: "When done." }
        triangles: { type: integer, description: "When done." }
        render_ms: { type: integer, description: "When done." }
        units: { type: integer, description: "Units charged (when done)." }
        cache: { type: string, enum: [hit, miss] }
        error:
          type: object
          description: When failed.
          properties:
            code: { type: string }
            message: { type: string }
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code:
              type: string
              enum:
                - bad_request
                - unauthorized
                - quota_exceeded
                - too_large
                - unsupported_format
                - invalid_model
                - rate_limited
                - fetch_failed
                - timeout
                - internal
            message:
              type: string
              description: Human-readable explanation. May change; branch on `code`.
            request_id:
              type: string
    Usage:
      type: object
      required: [plan, period, units_used, units_included, hard_limit]
      properties:
        plan:
          type: string
          description: Plan name.
          example: free
        period:
          type: string
          description: Billing period as `YYYY-MM`.
          example: "2026-11"
        units_used:
          type: integer
          example: 12
        units_included:
          type: integer
          example: 100
        hard_limit:
          type: boolean
          description: Whether requests are refused once the included units are used up.
          example: true
