Create and/or update multiple elements in a batch
POST
v2alpha/elements/batch-ingest
The desired element URNs can optionally be specified.
As part of the same batch elements can reference each other to form a hierarchy in a single request. You need to specify the element URN that should be used to store the new element for this.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/forma/integrate/v2alpha/elements/batch-ingest |
| Authentication Context | user context required |
| Required OAuth Scopes | data:read data:write |
| 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 |
* Required
Request
Query String Parameters
| authcontext* string | Authcontext for the request, such as the Forma project context. |
| s3Id string | If the payload for the request is larger than 6 MB it needs to be uploaded to S3 instead because AWS Lambda can only receive 6 MB. To do this make a GET request to /upload-link?authcontext=${authcontext}. You’ll get back an ID and a URL as JSON. First upload your payload by making a PUT request to the URL with your elements as the body. Then make a POST request with no body where s3Id is the ID you got from the request to /upload-link. |
* Required
Request
Body Structure
Expand all
| items* array | List of items to create or update. Maximum 1000 items can be specified. |
| oneOf* array:oneOf | |
| create* object | |
| operation* enum:string | Will always be: create |
| urn string | URN of the new element. The authcontext must match the current authcontext. |
| metadata object | |
| licensing object | |
| exportable* boolean | |
| attributions* array: object | |
| action* enum:string | Possible values: display, transfer |
| content* string | |
| url* string | |
| licenseUrl* string | |
| providerDescriptionUrl* string | |
| predecessor string | |
| properties object | |
| category string | |
| name string | |
| internalRepresentationReference string | |
| spacemakerObjectStorageReferences array: string | |
| geoReference object | |
| srid* number | |
| refPoint* | |
| anyOf* | |
| 0* array: number | |
| 1* array: number | |
| elementProvider string | |
| * | |
| representations object | |
| * one of | |
| linked object | |
| type* enum:string | Will always be: linked |
| blobId* string | Use the upload links endpoint to get a blob ID. Data must be uploaded before the blob ID can be used. |
| selection one of | |
| equals object | |
| type* enum:string | Will always be: equals |
| value* string | |
| startsWith object | |
| type* enum:string | Will always be: startsWith |
| value* string | |
| properties object | |
| * | |
| children array: object | |
| urn* string | URN of the new element. The authcontext must match the current authcontext. |
| transform array: number | Standard 4 by 4 transformation matrix as a flat array of 16 numbers in column-major order. |
| key string | A key must be unique within the same children list. Either all children must have keys specified or none of them.
Max length: 40 |
| update* object | |
| operation* enum:string | Will always be: update |
| urn* string | Reference to the element to update. |
| nextUrn string | URN of the new element. The authcontext must match the current authcontext. |
| metadata object | |
| licensing object | |
| exportable* boolean | |
| attributions* array: object | |
| action* enum:string | Possible values: display, transfer |
| content* string | |
| url* string | |
| licenseUrl* string | |
| providerDescriptionUrl* string | |
| predecessor string | |
| properties object | |
| category string | |
| name string | |
| internalRepresentationReference string | |
| spacemakerObjectStorageReferences array: string | |
| geoReference object | |
| srid* number | |
| refPoint* | |
| anyOf* | |
| 0* array: number | |
| 1* array: number | |
| elementProvider string | |
| representations object | |
| * one of | |
| linked object | |
| type* enum:string | Will always be: linked |
| blobId* string | Use the upload links endpoint to get a blob ID. Data must be uploaded before the blob ID can be used. |
| selection one of | |
| equals object | |
| type* enum:string | Will always be: equals |
| value* string | |
| startsWith object | |
| type* enum:string | Will always be: startsWith |
| value* string | |
| properties object | |
| * | |
| 1 | |
| children array: object | |
| urn* string | URN of the new element. The authcontext must match the current authcontext. |
| transform array: number | Standard 4 by 4 transformation matrix as a flat array of 16 numbers in column-major order. |
| key string | A key must be unique within the same children list. Either all children must have keys specified or none of them.
Max length: 40 |
* Required
Response
HTTP Status Code Summary
| 201 Created | The items in the response reflects the same order as in the input. Each item includes a reference to the new element. The response can be partial including failed items. |
| 400 Bad Request | Malformed 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 authcontext. Are you in the right region? |
| 500 Internal Server Error | Internal server error |
Response
Body Structure (201)
Expand all
| items array | Each item in the response corresponds to the item with the same index in the request. |
| oneOf array:oneOf | |
| ok object | Result for a successful operation. |
| status enum:string | Will always be: ok |
| urn string | |
| failed object | Result for a failed operation. |
| status enum:string | Will always be: failed |
| error object | |
| title string | |
| detail string | |
| errors array: object | |
| field string | |
| path array | |
| title string | |
| detail string |
Example
The items in the response reflects the same order as in the input. Each item includes a reference to the new element. The response can be partial including failed items.
Request
curl -v 'https://developer.api.autodesk.com/forma/integrate/v2alpha/elements/batch-ingest?authcontext=pro_123' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"operation": "create",
"urn": "urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305",
"metadata": {
"licensing": {
"exportable": true,
"attributions": [
{
"action": "display",
"content": "Open City Model is made available by BuildZero.Org under the Open Database License",
"url": "http://opendatacommons.org/licenses/odbl/1.0/"
},
{
"action": "transfer",
"content": "Open City Model is made available by BuildZero.Org under the Open Database License",
"url": "http://opendatacommons.org/licenses/odbl/1.0/"
}
],
"licenseUrl": "http://opendatacommons.org/licenses/odbl/1.0/",
"providerDescriptionUrl": "https://github.com/opencitymodel/opencitymodel"
},
"predecessor": ""
},
"properties": {
"category": "",
"name": "",
"internalRepresentationReference": "",
"spacemakerObjectStorageReferences": [
""
],
"geoReference": {
"srid": "",
"refPoint": {}
},
"elementProvider": ""
},
"representations": {},
"children": [
{
"urn": "urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305",
"transform": [
""
],
"key": ""
}
]
}
]
}'
Show More
Response
{
"items": [
{
"status": "ok",
"urn": "urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305"
}
]
}
Show More
