ℹ️

All requests must be made against an existing project.

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.

Status code	Description
`400`	Bad Request. Usually indicates invalid parameters or request format.
`401`	Unauthorized. Access tokens without the required scope will also return this error.
`403`	Forbidden. Likely due to license usage limits being reached/exceeded.
`404`	Not Found.
`500`	Internal Server Error.

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

🚧

Work in Progress

Authentication

🚧

Work in Progress

All requests must be authenticated with an access token. Access tokens may be copied from the Account page in the app.

Access tokens should be included in the request header in the following form:

Authorization: Bearer $access_token

Where $access_token is substituted with the token string.

🔒

Remember to keep your access tokens secure! Access tokens should be treated with the same care as a password.

One method to keep tokens safe from prying eyes is to retrieve them runtime by evaluating a (sub-)shell command:

curl -H "Authorization: Bearer ""$(pass show api/metafold3d.com)" https://api.metafold3d.com/

The above example uses pass, but any secure method of retrieving passwords on the command-line should work.

Note that if you have your shell history enabled, copying your tokens directly on to the command-line is also considered insecure—evaluating a shell command is different as the output of the command is not saved to history, only the command used to retrieve the token is saved.

Access Scopes

Scope	Description
`assets:read`	Query project assets.
`assets:write`	Make changes to project assets.
`jobs:read`	Query project jobs.
`jobs:write`	Dispatch new project jobs.

User Info

Endpoints

Get license information

GET /user/license

Response Status Codes

Status code	Description
`200`	OK

This endpoint uses the common error codes.

Response Body

Field	Description
`issued`	Issue time.
`expires`	Expiry time. May be `null` for licenses without an expiry date.
`expired`	Whether the license was expired at time of request.
`product`	Name of license tier.

Get remaining quota

GET /user/quota

Response Status Codes

Status code	Description
`200`	OK

This endpoint uses the common error codes.

Response Body

Field	Description
`project`	Number of remaining projects.
`import`	Number of remaining asset imports.
`export`	Number of remaining asset exports.
`simulation`	Number of remaining simulations run.

Get lifetime usage

GET /user/usage

Response Status Codes

Status code	Description
`200`	OK

This endpoint uses the common error codes.

Response Body

Field	Description
`project`	Number of lifetime projects.
`import`	Number of asset imports.
`export`	Number of asset exports.
`simulation`	Number of simulations run.

Assets

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

Resource

Field	Description
`id`	Asset ID.
`filename`	Asset filename (must be unique among other assets within the same project).
`size`	Object size in bytes.
`checksum`	Hash of object contents for checking integrity.
`created`	Asset creation time.
`modified`	Last modification time.

Endpoints

List project assets

GET /projects/<project>/assets

OAuth Scope — assets:read

Request Parameters

Field	Description
`sort` (Optional)	Sort string. Must be in the form `field:order`. `field` may be one of: `id`, `filename`, `size`, `created`, `modified`. `order` may be one of `-1` for descending or `1` for ascending. Resources are sorted in descending order by `id` by default.
`q` (Optional)	Query string. See Search Query Syntax for details. Supported search fields are: `id` and `filename`.

Response Status Codes

Status code	Description
`200`	OK

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

Field	Description
`download` (Optional)	Boolean. Either “true” or “1” is accepted. Response will include a `link` URL to download asset from.
`filename` (Optional)	String. Filename to give to the downloaded file. Useful for browser-initiated downloads.

Response Status Codes

Status code	Description
`200`	OK

This endpoint uses the common error codes.

Response Body

Field	Description
`link` (Optional)	URL to download asset from. The URL is only valid for 1 hour from the time of generation.
…	Asset resource

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

Status code	Description
`201`	Created

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

Status code	Description
`200`	OK

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

Status code	Description
`200`	OK

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

Field	Description
`id`	Job ID.
`name` (Optional)	Job name.
`type`	Job type.
`parameters`	JSON object with parameters corresponding to job type.
`created`	Job creation time.
`state`	Either: `pending`, `started`, `success`, or `failure`.
`assets`	List of generated asset resources.
`meta`	Additional JSON metadata attached to the job.

Types

ℹ️

Many of the job types will expect JSON graphs that define an implicit surface. These graphs must use a GenerateSamplePoints operator as the input point source, and output samples from a Threshold operator. Some jobs may even require the indices of either of these operators as they will need to read or modify operator parameters for processing.

Evaluate Graph

evaluate_graph

Evaluate any Metafold shape definition and store the results in Metafold output binary format.

Parameters

Parameter	Description
`graph`	JSON shape definition graph.

Generated Assets

Name	Description
`.bin`	Metafold binary file. Graph output results.

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

Parameter	Description
`graph`	JSON shape definition graph.
`point_source`	Integer. Index of the input `GenerateSamplePoints` operator.
`save_graph_output` (Optional)	Boolean. Defaults to false.

Generated Assets

Name	Description
`.bin` (Optional)	Metafold binary file. Graph output results.

Metadata

Name	Description
`surface_area`	Approx. surface area of shape.
`interior_volume`	Approx. interior volume of shape.
`relative_density`	Density (ratio) w.r.t. patch defined by the input `GenerateSamplePoints` operator.

Export to CLI File

export_cli

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

Parameters

Parameter	Description
`graph`	JSON shape definition graph.
`point_source`	Integer. Index of the input `GenerateSamplePoints` operator.
`layer_thickness`	Float. The distance in millimeters between layers.

Generated Assets

Name	Description
`.cli`	Generated CLI file in ASCII.

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

Parameter	Description
`graph`	JSON shape definition graph.
`point_source`	Integer. Index of the input `GenerateSamplePoints` operator.
`threshold_output`	Integer. Index of the output `Threshold` operator.
`grid_name` (Optional)	Name of the OpenVDB grid. Defaults to `sdf`.

Generated Assets

Name	Description
`.vdb`	OpenVDB file. Graph output results stored in a level set float grid with the background value set to the (positive) `Threshold` operator width.

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

Parameter	Description
`graph`	JSON shape definition graph.
`point_source`	Integer. Index of the input `GenerateSamplePoints` operator.
`image_width`	Integer.
`image_height`	Integer.
`size_y`	Number. Size of slice plane along Y-axis, i.e. image height, in world space.
`slice_spacing` (Optional)	Number. Spacing between slices along Z-axis. Must be non-zero. Defaults to 0.05.
`slice_count` (Optional)	Integer. Number of slices along Z-axis. Multiple slices are stored in a ZIP archive. Defaults to 1.
`offset` (Optional)	JSON list of three numbers. Translation offset in world space.

Generated Assets

Name	Description
`.png`/`.zip`	PNG for a single slice. ZIP archive with PNG sequence for multiple slices.

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

Parameter	Description
`graph`	JSON shape definition graph.
`point_source`	Integer. Index of the input `GenerateSamplePoints` operator.
`file_type` (Optional)	`obj`, `ply`, `stl`, or `3mf`. Defaults to `stl`.
`close_boundary` (Optional)	Boolean. Defaults to true.

Generated Assets

Name	Description
`.obj`/`.ply`/`.stl`	Generated mesh file. Type of file depends on the specified `file_type`.

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

Parameter	Description
`mesh_filename`	Mesh filename. This should correspond to the filename of an asset resource.
`max_resolution` (Optional)	Integer. Maximum resolution along the longest axis. Resulting grid samples will be uniformly spaced.
`resolution` (Optional)	JSON list of three integers. Sample grid resolution.
`padding` (Optional)	JSON list of three numbers. Additional padding to extend the bounds in each direction by.

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

Generated Assets

Name	Description
`.bin`	Metafold binary file. Signed distances to the triangle mesh sampled on a regular grid.

Metadata

Name	Description
`graph`	Metafold shape definition used to generate the volume asset.
`patch`	Object with `offset`, `size`, and `resolution` of generated volume asset.

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.

Parameters

Parameter	Description
`mesh_filename`	Filename of STEP file. This should correspond to the filename of an asset resource.
`max_resolution` (Optional)	Integer. Maximum resolution along the longest axis. Resulting grid samples will be uniformly spaced.
`resolution` (Optional)	JSON list of three integers. Sample grid resolution.
`padding` (Optional)	JSON list of three numbers. Additional padding to extend the bounds in each direction by.

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

Generated Assets

Name	Description
`.bin`	Metafold binary file. Signed distances to the triangle mesh sampled on a regular grid.

Metadata

Name	Description
`graph`	Metafold shape definition used to generate the volume asset.
`patch`	Object with `offset`, `size`, and `resolution` of generated volume asset.

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:

Element name	Property name	Property data type
vertex	u	float
vertex	v	float
vertex	w	float
face	vertex_indices	int[3]

Parameters

Parameter	Description
`mesh_filename`	Mesh filename. This can be found from the asset resource.

Generated Assets

Name	Description
`.ply`	Extracted PLY buffer file. Compatible with the InterpolateBoundaryCoords operator.

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:

Element name	Property name	Property data type
vertex	x	float
vertex	y	float
vertex	z	float
face	vertex_indices	int[3]
face	material_index	uchar

Parameters

Parameter	Description
`mesh_filename`	Mesh filename. This can be found from the asset resource.

Generated Assets

Name	Description
`.ply`	Extracted PLY buffer file. Compatible with the InterpolateBoundaryCoords operator.

Compute Polycube Parametrization

compute_polycube_parametrization

Compute a parametrization from a watertight triangle mesh, used to produce conformal lattices (

Guide — Conforming Lattices Alpha

Parameters

Parameter	Description
`mesh_filename`	Mesh filename. This can be found from the asset resource.

Generated Assets

Name	Description
`.ply`	Extracted PLY buffer file. Compatible with the InterpolateBoundaryCoords operator.

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.

‣

Snippet example boilerplate

// Global variables and helper functions may also be defined before the main custom
// shape function (see surface).
const float sphere_radius = 0.5;

/**
 * Helper function to compute the signed distance function (SDF) of a sphere.
 *
 * @param[in] position Position of sample point.
 * @param[in] radius   Radius of sphere geometry.
 *
 * @return Distance from sample point to sphere.
 */
float sphere_sdf(in vec3 position, in float radius) {
	return length(position) - radius;
}

/**
 * Custom shape function that is called for every sample point in the graph request.
 *
 * The implementation should at the very least return an indicator function where
 * interior points are < 0, exterior points are > 0, and points on the surface of
 * the shape = 0.
 *
 * @param[in] position Position of sample point.
 *
 * @return Distance from sample point to custom shape.
 */
float surface(in vec3 position) {
	return sphere_sdf(position, sphere_radius);
}

Parameters

Parameter	Description
`snippet`	GLSL code snippet.
`save_output` (Optional)	Save output shader binary. Avoid saving intermediate compile tests if possible.

Generated Assets

Name	Description
`.spv`	Compile shader binary. Compatible with the SampleCustomShape operator.

Endpoints

List project jobs

GET /projects/<project>/jobs

OAuth Scope — jobs:read

Request Parameters

Field	Description
`sort` (Optional)	Sort string. Must be in the form `field:order`. `field` may be one of: `id`, `name`, `created`. `order` may be one of `-1` for descending or `1` for ascending. Resources are sorted in descending order by `id` by default.
`q` (Optional)	Query string. See Search Query Syntax for details. Supported search fields are: `id`, `name`, `type`, and `state`.

Response Status Codes

Status code	Description
`200`	OK

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

Status code	Description
`200`	OK

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

Field	Description
`type`	Job type name.
`parameters`	JSON object with parameters corresponding to job type.
`name` (Optional)	Label for the job.

Response Status Codes

Status code	Description
`202`	Accepted. Response includes `link` URL to query for job status/progress monitoring.

Response Body

Field	Description
`link`	URL to query for job status/progress monitoring.
…	Job resource. Some fields may be empty at time of acceptance.

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

Status code	Description
`202`	Accepted. Job is queued/processing.
`201`	Created
`400`	Bad Request
`500`	Internal Server Error

Response Body

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

Field	Description
`state`	Any of `pending`, `started`, `progress`, `retry`, `failure`, `success`.
`progress` (Optional)	JSON object with `count` and `total`, useful for displaying progress feedback. Only available in `progress` state.

Update a project job

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

OAuth Scope — jobs:write

Request Parameters

Field	Description
`name` (Optional)	Label for the job.

Response Status Codes

Status code	Description
`200`	OK

This endpoint uses the common error codes.

Response Body

Job resource

Simulations

🚧 WIP

Metafold REST API

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 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