Conventions

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:

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.

<aside> 🚧 Work in Progress

</aside>

Authentication

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

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