<aside> ℹ️ All requests must be made against an existing project.

</aside>

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:

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

Pagination

<aside> 🚧 Work in Progress

</aside>

Authentication

Please see our guide on Authenticating to the REST API.

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

| --- | --- |

Response Status Codes

| --- | --- |

This endpoint uses the common error codes.

Response Body

| --- | --- |

Create a new project asset