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