• Conventions
• Parameters
• Responses
• Error Codes
• Search Query Syntax
• Pagination
• Authentication
• Access Scopes
• User Info
• Endpoints
• Get license information
• Get remaining quota
• Get lifetime usage
• Assets
• Endpoints
• List project assets
• Get a project asset
• Create a new project asset
• Update a project asset
• Delete a project asset
• Jobs
• Types
• Evaluate Graph
• Evaluate Shape
• Evaluate Metrics
• Export to CLI File
• Export OpenVDB Volume
• Export Slices
• Export Triangle Mesh
• Sample Triangle Mesh
• Sample STEP File
• Extract Parametrization
• Parametrize by Face Label
• Compute Polycube Parametrization
• Compile Custom Shape
• Endpoints
• List project jobs
• Get a project job
• Create a new project job
• Update a project job
• Simulations

Conventions

Parameters

GET requests should send parameters as a query string following the URL, e.g. https://api.metafold3d.com/projects/1/assets/1?download=true.

POST/PATCH/PUT requests should send parameters encoded as multipart/form-data (as standard for HTML forms with a file part) or application/json.

Responses

Response bodies are encoded as application/json, including errors.

Error Codes

The API will respond with the following standard error codes unless specified otherwise.

Client errors (400, 401, 404) will typically include a JSON body with a msg field containing a human-readable description of the problem.

A request with invalid parameters may include more information in the form of a list of errors:

{
	"errors: [
		{
			"field": "type",
			"msg": "Field is required",
		},
		...
	]
}

Search Query Syntax

Lists of resources may be searched/filtered using the optional q (query) parameter. The search query uses a simple syntax:

• Search terms must be in the form field:query
• Valid values for field depend on the resource type, e.g. for Asset resources you may search the filename field
• query is the search string. A wildcard * may be used to match any sequence of zero or more characters. The search string may optionally be quoted.
• The search term may optionally be preceded by a bang ! to negate the filter
• Some examples of valid search terms:
• name:foo search for an exact match
• name:*f* search for any resource with “f” in the name
• name:"My Resource" search for an exact match
• !name:"My *" search for any resource that does not start with “My “
• Multiple search terms may be applied using the AND operator
• Only resources that match ALL the terms will be included in the response
• e.g. type:evaluate_graph AND state:success search for successful Evaluate Graph jobs only

OR operator and grouping of search terms not currently supported. Support for searching numeric and date time ranges is planned.

Pagination

Authentication

Please see our guide on Authenticating to the REST API.

Access Scopes

User Info

Endpoints

Get license information

GET /user/license

Response Status Codes

This endpoint uses the common error codes.

Response Body

Get remaining quota

GET /user/quota

Response Status Codes

This endpoint uses the common error codes.

Response Body

Get lifetime usage

GET /user/usage

Response Status Codes

This endpoint uses the common error codes.

Response Body

Assets

Assets are (typically) large binary files that either uploaded by users, or generated by jobs.

Resource

Endpoints

List project assets

GET /projects/<project>/assets

OAuth Scope — assets:read

Request Parameters

Response Status Codes

This endpoint uses the common error codes.

Response Body

List of asset resources.

Get a project asset

GET /projects/<project>/assets/<asset>

OAuth Scope — assets:read

Retrieve the asset resource. To download the asset file, add the parameter download=true to the request and follow the link in the response.

Request Parameters

Response Status Codes

This endpoint uses the common error codes.

Response Body

Create a new project asset

POST /projects/<project>/assets

OAuth Scope — assets:write

An upload file must be included in the request via multipart/form-data. The filename for the asset is determined by the filename of the attached file.

Only the following file types are allowed:

• model/obj
• model/stl
• application/octet-stream (for file types without a registered MIME type, e.g. STL)

Response Status Codes

This endpoint uses the common error codes.

Response Body

Asset resource

Update a project asset

PATCH/PUT /projects/<project>/assets/<asset>

OAuth Scope — assets:write

Upload a new file for an existing asset. Note that the original file is first deleted. See the POST endpoint for guidance on file types.

Response Status Codes

This endpoint uses the common error codes.

Response Body

Asset resource

Delete a project asset

DELETE /projects/<project>/assets/<asset>

OAuth Scope — assets:write

Response Status Codes

This endpoint uses the common error codes.

Jobs

Jobs are responsible for consuming assets (typically specified via the job parameters) and generating zero or more assets. Each job resource contains a list of the assets it has created. Some jobs may also output additional metadata (meta) which can be queried directly from the job resource.

Resource

Types

Evaluate Graph

evaluate_graph

Evaluate any Metafold graph and store the results in Metafold output binary format. Binary output may optionally be zlib compressed.

Parameters

Generated Assets

Evaluate Shape

evaluate_shape

Evaluate any Metafold shape graph and store the results in Metafold output binary format. Binary output may optionally be zlib compressed (see Evaluate Graph).

This differs from the Evaluate Graph job in that we assume the input graph represents a shape function, i.e. $f(x, p)$ where $x$ is a grid of regularly-spaced sample points in $\mathbb{R}^3$ and $p$ are the shape parameters (in other words a JSON graph that starts with a GenerateSamplePoints operator and outputs samples).

client.jobs.run("evaluate_shape", {
    "graph": graph,
    "size": [2.0, 2.0, 2.0],
    "max_resolution": 256,
})

The Threshold operator may also be omitted from the end of the shape graph and will be automatically appended as needed.

Parameters

Generated Assets

Metadata

Evaluate Metrics

evaluate_metrics

Evaluate the approximate interior volume and surface area of the implicit surface defined by the given Metafold shape definition. Units for the metrics depend on the configured project settings, e.g. if the project is defined in millimeters (mm), then the interior volume is assumed to be mm³ and the surface area mm².

Similar metrics may be computed on a meshed surface, but this method circumvents meshing entirely, which is more resource-efficient and faster in general.

Parameters

Generated Assets

Metadata

Export to CLI File

export_cli

Create a Common Layer Interface (CLI) file for printing geometries.

Parameters

Generated Assets

Export OpenVDB Volume

export_vdb

Evaluate the implicit surface defined by the given Metafold shape definition and store the results as an OpenVDB volume. Until the 3MF Volumetric Extension has been finalized, there are no plans to support any other volumetric formats in the near term.

Parameters

Generated Assets

Export Slices

export_slices

Slice the implicit surface defined by the given Metafold shape definition, usually for resin-based 3D printers, e.g. Stereolithography (SLA), Digital Light Processing (DLP). The slicing parameters define the slice planes used to sample cross sections of the implicit surface. The width of the slice planes (in world space) is determined by multiplying size_y by the image aspect ratio ($\frac{width}{height}$) in order to maintain uniform scale and produce square pixels.

Each slice is a PNG bitmap with distance values less-than or close to zero are mapped to white (maximum luminance), and vice versa for values above zero.

Parameters

Generated Assets

Export Triangle Mesh

export_triangle_mesh

Mesh the implicit surface defined by the given Metafold shape definition. The resolution of the output mesh is controlled by the resolution of the point_source operator.

Parameters

Generated Assets

Sample Triangle Mesh

sample_triangle_mesh

Sample the given triangle mesh asset on a regular grid to produce a volume asset (stored in Metafold binary output format). The grid is fitted to the exact (with optional padding) axis-aligned bounding box of the mesh.

The generated volume may be used in a handful of graph evaluation operations by first loading the asset using the LoadVolume operator. The loaded volume may then be sampled directly with the SampleVolume or ComputeNormals operators, or used to accelerate the SampleTriangleMesh operator when sampling the original mesh.

Parameters

⚠️ Either one of max_resolution or resolution must be supplied, but not both at the same time.

Generated Assets

Metadata

Sample STEP File

sample_step_file

Sample the given STEP (.step/.stp) file on a regular grid to produce a volume asset (stored in Metafold binary output format). The grid is fitted to the exact (with optional padding) axis-aligned bounding box of the mesh.

The generated volume may be used in a handful of graph evaluation operations by first loading the asset using the LoadVolume operator. The loaded volume may then be sampled directly with the SampleVolume or ComputeNormals operators, or used to accelerate the SampleTriangleMesh operator when sampling the original mesh.

Parameters

⚠️ Either one of max_resolution or resolution must be supplied, but not both at the same time.

Generated Assets

Metadata

Extract Parametrization

extract_parametrization

Extract a parametrization used to produce conformal lattices (Guide — Conforming Lattices Alpha) from a PLY mesh asset. The PLY mesh is expected to have the following elements and properties:

Parameters

Generated Assets

Parametrize by Face Label

parametrize_by_face_label

Create a parametrization used to produce conformal lattices (Guide — Conforming Lattices Alpha) from a PLY mesh asset containing per-face labels. The PLY mesh is expected to have the following elements and properties:

Parameters

Generated Assets

Compute Polycube Parametrization

compute_polycube_parametrization

Compute a parametrization from a watertight triangle mesh, used to produce conformal lattices (Guide — Conforming Lattices Alpha).

Parameters

Generated Assets

Compile Custom Shape

compile_custom_shape

Compile custom shape code snippet. The compiled output may be used as shader_data in the SampleCustomShape with file_type set to ShaderBinarySPIRV. The snippet should implement a function with the signature float surface(in vec3 position and return an indicator function where the interior points are $< 0$, exterior points are $> 0$, and points on the surface $= 0$. The job will fail with a helpful error message if the shader compilation fails.

Parameters

Generated Assets

Endpoints

List project jobs

GET /projects/<project>/jobs

OAuth Scope — jobs:read

Request Parameters

Response Status Codes

This endpoint uses the common error codes.

Response Body

List of job resources.

Get a project job

GET /projects/<project>/jobs/<job>

OAuth Scope — jobs:read

Response Status Codes

This endpoint uses the common error codes.

Response Body

Job resource

Create a new project job

POST /projects/<project>/jobs

OAuth Scope — jobs:write

All jobs are processed asynchronously and return 202 Accepted on success. 202 Accepted only indicates that the request itself was valid and a job has been queued for processing. In order to monitor job status/progress, clients may poll the link URL in the response body.

Request Parameters

Response Status Codes

Response Body

Querying the link URL will similarly return 202 Accepted if the job is still being processed. Otherwise the standard response status codes and body of a synchronous POST request should be expected. After receiving a response not equal to 202, the link URL is no longer guaranteed to be available nor produce a meaningful response. Instead the resulting job should be fetched through the standard GET endpoint.

Response Status Codes

Response Body

Job resource on 201 Created. Otherwise refer to the following table:

Update a project job

PATCH /projects/<project>/jobs/<job>

OAuth Scope — jobs:write

Request Parameters

Response Status Codes

This endpoint uses the common error codes.

Response Body

Job resource

Simulations

🚧 WIP