Metafold REST API

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

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.

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

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

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
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 (widthheight\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, or stl. Defaults to stl. 3MF support coming soon!
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.

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

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

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

).

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< 0, exterior points are >0> 0, and points on the surface =0= 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

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