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

Error Codes

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",
		},
		...
	]
}

Pagination

🚧 Work In Progress

Authentication

All requests must be authenticated with an access token. Access tokens may be generated manually through the web app.

🚧 Work In Progress

Permission to use API features must be specifically granted to tokens through access scopes.

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

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.

User Info

Endpoints

Get license information

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 JSON object of license features.
product.name Unique product name.
product.project_max Maximum number of projects allowed.
product.import_max Maximum number of asset imports allowed.
product.export_max Maximum number of asset exports allowed. Only successful export jobs are counted against this limit.
product.allow_conform Whether conformal lattice features may be used.
product.allow_grading Whether grading features may be used.

Get quota usage

GET /user/quota

Response Status Codes

Status code Description
200 OK

This endpoint uses the common error codes.

Response Body

Field Description
project_count Number of active projects.
import_count Number of asset imports over the current billing period.
export_count Number of asset exports over the current billing period.

Assets

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

<aside> 💡 When accessing asset contents using the Lightcycle Python package, you may use the json convenience method to load the contents of JSON assets as a dictionary.

</aside>

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.

Endpoints

List project assets

GET /projects/<project>/assets

OAuth Scope — assets:read

Response Status Codes

Status code Description
200 OK

This endpoint uses the common error codes.

Response Body

List of asset resources.

Get a project asset

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

Field Description
download (Optional) Boolean. Either “true” or “1” is accepted. Response will include a link URL to download asset from.

Response Status Codes

Status code Description
200 OK

This endpoint uses the common error codes.

Response Body

Field Description
link (Optional) URL to download asset from. The URL is only valid for 1 hour from the time of generation.
… https://metafold3d.notion.site/Lightcycle-API-059f01a419a74811a9d2dcafe75c871b

Create a new project asset

POST /projects/<project>/assets

OAuth Scope — assets:write

An upload file must be included in the request via multipart/form-data. The filename for the asset is determined by the filename of the attached file.

Only the following file types are allowed:

Response Status Codes