v1alpha/elements-batch
Retrieve multiple elements
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/forma/element-service/v1alpha/elements-batch |
| Authentication Context | user context required |
| Required OAuth Scopes | data:read |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow. |
| X-Ads-Region string | Specifies the geographical location (region) of the service. US or EMEA. Defaults to US. |
| Content-Type* string | Must be application/json |
Request
Query String Parameters
| authcontext* string | The authcontext of the resource you are requesting |
Request
Body Structure
| urns* array: string |
Response
HTTP Status Code Summary
| 200 OK | The response will contain all elements that were successfully retrieved, as well as an error object for each failed element. |
| 302 | Clients should follow redirects, as the response might be stored somewhere else |
| 400 Bad Request | Bad request. The request body is not valid according to the schema. See response for details. |
| 401 Unauthorized | Bearer token is not valid |
| 403 Forbidden | Token does not have access to the specified project. Are you in the right region? |
| 500 Internal Server Error | Internal server error |
Response
Body Structure (200)
| results object | Mapping from URN to elements |
| * object | Learn more about the element system here: https://aps.autodesk.com/en/docs/forma/v1/working-with-forma/element-system/ |
| urn string | Unique Resource Name (URN) for an element, used to identify a specific
revision of an element.
The element URN scheme is urn:adsk-forma-elements:{system}:{authcontext}:{id}:{revision}. |
| metadata object | Metadata about an element. Does not describe the element itself, but rather the context in which it has been created/updated and potential licensing information. |
| predecessor string | Unique Resource Name (URN) for an element, used to identify a specific
revision of an element.
The element URN scheme is urn:adsk-forma-elements:{system}:{authcontext}:{id}:{revision}. |
| createdAt datetime: ISO 8601 | Creation timestamp, in ISO8601 datetime format. |
| createdBy string | |
| licensing object | Information related to the licensing governing the use and transfer of this element. |
| exportable boolean | Whether or not data can be transferred out of Forma, for example by downloading a data file or sending a project to Revit. |
| attributions array: object | Attribution requirements that must be followed. Empty if there are no requirements |
| action enum:string |
Possible values: |
| content string | |
| url string | |
| licenseUrl string | Link to the original license for the data |
| providerDescriptionUrl string | Link to the providers description on how the license should be interpreted. For auditing purposes. |
| properties object | Properties of an element are inherent attributes which are independent
of the representation used to interpret its geometry.
For example, setting an element’s virtual property to true will indicate that the element should not be included as a physical object which e.g. blocks sun rays – regardless of which representation you are looking at. |
| category string | The category is used to indicate the user intent of the element. It can
be used to group and filter top-level elements in the UI.
The category is a string, and can be any value. |
| noiseIgnore boolean | For elements with a volumeMesh representation, this flag signals
that the element should be ignored when analyzing traffic noise. In
contrast to the virtual property, it does _not_ imply that the
element isn’t a physical object – just that it does not block
noise.
Typically used for vegetation elements, since it is common practice to ignore vegetation when performing traffic noise analysis. |
| treatAsVegetationInWindAnalysis boolean | If true, and if the element has a volumeMesh representation, the wind analysis will interpret the element as vegetation modelled as a porous medium. See this help center article for details about the implementation. |
| virtual boolean | This field can be used to identify something that isn’t real, like a constraint or an illustrative boy with balloon. If this is set, analyses and possibly other modes will ignore the element. |
| functionId string | Deprecated: This field is being removed. Function tagging will be
re-introduced using a new concept.
This field will assign a function to the element, which will dictate the color with which it is rendered in addition to providing function breakdowns in Area Metrics. |
| trafficData | Providing this field will include the element as a noise source in the rapid and detailed noise analysis. |
| anyOf | Providing this field will include the element as a noise source in the rapid and detailed noise analysis. |
| 0 object | Properties required for road traffic data |
| 1 object | Properties required for rail traffic data |
| * | |
| representations object | Representations provide ways for an element to be interpreted. An element can have zero, one, or several representations which unlock different functionality. |
| * one of | |
| LinkedRepresentation object | The data for a linked representation must be fetched by a separate API using the blob ID. |
| type object | Will always be: linked |
| blobId string | Blob ID. Used to retrieve the data for this representation. |
| selection one of | The underlying data for a representation can be shared
across multiple elements/representations.
This field, if present, should be used to select the relevant parts from the data that belongs to this representation. The exact details is specific for the representation/format, but in most cases this is used with an ID in the data and comparing it against this value using the specified operator. |
| 0 object | |
| type object | Will always be: equals |
| value string | The relevant data for the representation will be under this value. |
| 1 object | |
| type object | Will always be: startsWith |
| value string | Any value with this prefix is relevant for the representation. |
| properties object | Additional information about the representation. |
| * | |
| EmbeddedJsonRepresentation object | The data for an embedded representation can be accessed directly under the data key. |
| type object | Will always be: embedded-json |
| data object | |
| selection one of | The underlying data for a representation can be shared
across multiple elements/representations.
This field, if present, should be used to select the relevant parts from the data that belongs to this representation. The exact details is specific for the representation/format, but in most cases this is used with an ID in the data and comparing it against this value using the specified operator. |
| 0 object | |
| type object | Will always be: equals |
| value string | The relevant data for the representation will be under this value. |
| 1 object | |
| type object | Will always be: startsWith |
| value string | Any value with this prefix is relevant for the representation. |
| properties object | Additional information about the representation. |
| * | |
| EmbeddedBinaryRepresentation object | The data for an embedded representation can be accessed directly under the data key. |
| type object | Will always be: embedded-binary |
| data string | |
| selection one of | The underlying data for a representation can be shared
across multiple elements/representations.
This field, if present, should be used to select the relevant parts from the data that belongs to this representation. The exact details is specific for the representation/format, but in most cases this is used with an ID in the data and comparing it against this value using the specified operator. |
| 0 object | |
| type object | Will always be: equals |
| value string | The relevant data for the representation will be under this value. |
| 1 object | |
| type object | Will always be: startsWith |
| value string | Any value with this prefix is relevant for the representation. |
| properties object | Additional information about the representation. |
| * | |
| children array: object | An element can include other elements as children, which results in a tree structure. Elements may be referenced multiple times, with different transforms and under different parents. |
| urn string | Unique Resource Name (URN) for an element, used to identify a specific
revision of an element.
The element URN scheme is urn:adsk-forma-elements:{system}:{authcontext}:{id}:{revision}. |
| key string | Unique id under parent. Used to build up paths. Prefer short values for space efficiency. |
| transform array: number | Flat array of 16 numbers representing column-major 4x4 affine matrix.
Translation values use metres as unit.
The matrix is applied to the element’s geometry, and the resulting geometry is then transformed by the parent’s matrix. |
| name string | User defined naming of this specific reference, typically used to distinguish elements in eg. UI listings |
| errors object | Mapping from URN to error |
| * object | Mapping from blob IDs to errors. |
| * object | |
| code enum:string | Supported error codes are skipped, not_found and other.
If the error code skipped is used, it means the element system
was unable to process the requested item, and the client should
issue another request for that item (optionally together with multiple
others). This error code can be used in cases where the total size
of the result or processing time exceeds a certain system-specific
threshold, to ensure a valid partial response can be given.
This must be expected for both elements and blobs batch operations.
The client should repeat this process until either all items have
been processed or the system only returns errors with this code.
Possible values: |
| message string |
Example
Request
curl -v 'https://developer.api.autodesk.com/forma/element-service/v1alpha/elements-batch?authcontext=pro_abcd' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
-d '{
"urns": [
"urn:adsk-forma-elements:parametric:pro_abcd:c80d7b660e891:1712753285802",
"urn:adsk-forma-elements:integrate:myauthcontext:myelementid3:myrevision"
]
}'
Response
{
"results": {
"urn:adsk-forma-elements:parametric:pro_abcd:c80d7b660e891:1712753285802": {
"urn": "urn:adsk-forma-elements:parametric:pro_abcd:c80d7b660e891:1712753285802",
"children": [
{
"key": "myFavoritechild",
"transform": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1
],
"urn": "urn:adsk-forma-elements:some-element:pro_abcd:some-id:revision"
}
],
"properties": {
"name": "Surrounding Building 1",
"category": "building"
},
"representations": {
"volumeMesh": {
"type": "linked",
"selection": {
"type": "equals",
"value": "c80d7b660e891"
},
"blobId": "parametric:eyJlbGVtZW50SWQiOiJjODBkN2I2NjBlODkxIiwicmV2aXNpb24iOiIxNzEyNzUzMjg1ODAyIiwidHlwZSI6ImdsYiJ9"
},
"grossFloorAreaPolygons": {
"type": "embedded-json",
"data": [
{
"grossFloorPolygon": [
[
[
-268.8674135512906,
-129.91293074777607
],
[
-273.52954996440917,
-140.9702579142062
],
[
-258.78644707583567,
-147.1864397983643
],
[
-254.1243106627171,
-136.12911263193416
],
[
-268.8674135512906,
-129.91293074777607
]
]
],
"elevation": 0,
"areaType": "UNASSIGNED"
}
]
}
}
},
"urn:adsk-forma-elements:integrate:myauthcontext:myelementid3:myrevision": {
"properties": {
"category": "building"
},
"representations": {
"volumeMesh": {
"type": "linked",
"selection": {
"type": "equals",
"value": "abcdefghijkl"
},
"blobId": "integrate:eyJlbGVtZW50SWQiOiJjODBkN2I2NjBlODkxIiwicmV2aXNpb24iOiIxNzEyNzUzMjg1ODAyIiwidHlwZSI6ImdsYiJ9"
}
}
}
},
"errors": []
}
