<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>
<aside> 🚧 Work in Progress
</aside>
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.
<aside> 🔒 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.
</aside>
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
| --- | --- |
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