Request

Response

    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
    *
    embedded-json
    object
    type*
    enum:string
    Will always be: embedded-json
    data
    object
    A maximum of approximately 100 KiB of JSON data can be provided. Use a linked representation if you risk exceeding this.
    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
    *
    embedded-json
    object
    type*
    enum:string
    Will always be: embedded-json
    data
    object
    A maximum of approximately 100 KiB of JSON data can be provided. Use a linked representation if you risk exceeding this.
    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
    *
    2
    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