<aside> ℹ️ All requests must be made against an existing project.
</aside>
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.
Response bodies are encoded as application/json, including errors.
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",
},
...
]
}
Lists of resources may be searched/filtered using the optional q (query) parameter. The search query uses a simple syntax:
field:query
field depend on the resource type, e.g. for Asset resources you may search the filename fieldquery 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.! to negate the filtername:foo search for an exact matchname:*f* search for any resource with “f” in the namename:"My Resource" search for an exact match!name:"My *" search for any resource that does not start with “My “AND operator
type:evaluate_graph AND state:success search for successful Evaluate Graph jobs onlyOR operator and grouping of search terms not currently supported. Support for searching numeric and date time ranges is planned.
<aside> 🚧 Work in Progress
</aside>
Please see our guide on Authenticating to the REST API.
| 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. |
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 /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 /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 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. |
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 /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
| --- | --- |