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

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

<aside> 🚧 Work in Progress

</aside>

Authentication

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

Access Scopes

User Info

Endpoints

Get license information

GET /user/license

Response Status Codes

This endpoint uses the common error codes.

Response Body

Get remaining quota

GET /user/quota

Response Status Codes

This endpoint uses the common error codes.

Response Body

Get lifetime usage

GET /user/usage

Response Status Codes

This endpoint uses the common error codes.

Response Body

Assets

Assets are (typically) large binary files that either uploaded by users, or generated by jobs.

Resource

Endpoints

List project assets

GET /projects/<project>/assets

OAuth Scope — assets:read

Request Parameters

Response Status Codes