Integrate API
The Integrate API provides a mechanism to store geometry from outside Forma. When the geometry is stored it can be retrieved by other systems through the Element API and used in the product.
These APIs are accessible to your generator backend service with the two-legged token explained in the auth section.
Supported geometry
You can store a few different types of geometry:
- GLB files
- Meshes by vertices and faces
- GeoJSON
Storing geometry
Endpoint with payload in body (limited to 6 MB):
POST /api/integrate/elements?authcontext={authcontext}
The authcontext parameter is either a project ID or a workspace ID.
Payload
The JSON payload schema, including detailed information about
supported geometry types, is documented via the CreateElementHierarchy type at:
https://app.autodeskforma.com/forma-embedded-view-sdk/docs/
The elements in this payload can be organized in the same way as described in the Element System, as a tree structured of multiple elements, each having separate properties.
Creating large elements with S3
Create a presigned link to S3 where you can upload the data:
GET /api/integrate/upload-link?authcontext={authcontext}
Example response
{
"id": "d67bb49d-d2e8-40dc-aae0-059b2e4ffcf7",
"url": "https://integrate-api-payload-eu-west-1-prod.s3.eu-west-1.amazonaws.com/..."
}
You can now take the original integrate endpoint body and write it to the S3 URL:
PUT <presigned-s3-url>
The integrate endpoint can now be invoked with a reference
to the uploaded body using the s3Id parameter.
POST /api/integrate/elements?authcontext={authcontext}&s3Id={S3Id}
Error messages
If the payload is invalid, the API will respond with HTTP status 400 (bad request) with error information in the body structured as:
type ErrorResponse = {
title: string
detail: string
errors?:
| {
field: string | null
path: (string | number)[] | null
title: string
detail: string
}[]
| undefined
}
Example error responses:
{
"title": "Invalid input in field",
"detail": "See `errors` for information about which parts of the request failed to validate",
"errors": [
"field": "querystring/authcontext",
"path": ["querystring", "authcontext"],
"title": "Invalid input in field",
"detail": "Required"
]
}
{
"title": "Invalid input in field",
"detail": "See `errors` for information about which parts of the request failed to validate",
"errors": [
"field": "body/elements/some-element/children/0",
"path": ["body", "elements", "some-element", "children", 0],
"title": "Invalid input in field",
"detail": "Expected string, received number"
]
}
