Request

Response

    Update an element
    POST

    v2alpha/elements/{elementUrn}/update

    Create a new element based on the existing element. The element must belong to integrate system.

    The update will be merged onto the existing element. The merge happens for each individual property and representation, but not deeper. If you want to remove a field you must set it to null.

    If you want to store a full representation you can also use the create element endpoint and specifying the predecessor metadata field explicitly. In that case there will only be a reference to the predecessor but no other data from the previous element will be kept.

    The desired element URNs can optionally be specified.

    Resource Information

    Method and URI
    POST
    https://developer.api.autodesk.com/forma/integrate/v2alpha/elements/{elementUrn}/update
    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

    URI Parameters

    elementUrn
    string

    Request

    Query String Parameters

    authcontext*
    string
    Authcontext for the request, such as the Forma project context.
    * Required

    Request

    Body Structure

    Expand all
    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
    Returns a reference to the created element.
    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)

    urn
    string

    Example

    Returns a reference to the created element.

    Request

    curl -v 'https://developer.api.autodesk.com/forma/integrate/v2alpha/elements/urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305/update?authcontext=pro_123' \
      -X 'POST' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
      -H 'Content-Type: application/json' \
      -d '{
            "properties": {
              "foo": "bar"
            },
            "representations": {
              "volumeMesh": {
                "type": "linked",
                "blobId": "c29tZXZhbHVlCg=="
              }
            },
            "children": [
              {
                "urn": "urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305"
              }
            ]
          }'
    
    Show More

    Response

    {
      "urn": "urn:adsk-forma-elements:integrate:pro_example:f0c60b7b-d49f-43a1-9a34-a6834897f880:1719505510305"
    }