<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
.
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",
},
...
]
}
🚧 Work In Progress
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>
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 | 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 /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 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. |
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 /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 |
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:
model/obj
model/stl
application/octet-stream
(for file types without a registered MIME type, e.g. STL)Response Status Codes