Request

Response

    Update an existing element
    POST

    v1alpha/elements/{elementId}

    Deprecated

    Creates a new element with a new revision under the specified element ID. Useful to keep track of changes in geometry in the same logically evolving entity.

    Deprecated. Please migrate to v2.

    Resource Information

    Method and URI
    POST
    https://developer.api.autodesk.com/forma/integrate/v1alpha/elements/{elementId}
    Authentication Context
    user context optional
    Required OAuth Scopes
    data:read data:write
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is obtained via either a two-legged or 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

    elementId
    string

    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.
    nextRevision
    string
    Optionally specify the element revision. Must be an epoch timestamp in ms.
    * Required

    Request

    Body Structure

    Expand all
    rootElement*
    string
    elements*
    object
    **
    object
    id*
    string
    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
    geometry
    anyOf
    0
    object
    type*
    enum:string
    Will always be: File
    format*
    enum:string
    Will always be: glb
    s3Id*
    string: UUID
    nodeId
    string
    doubleSided
    boolean
    1
    object
    type*
    enum:string
    Will always be: Inline
    format*
    enum:string
    Will always be: Mesh
    doubleSided
    boolean
    verts*
    array: number
    faces*
    array: number
    2
    object
    type*
    enum:string
    Will always be: Inline
    format*
    enum:string
    Will always be: GeoJSON
    geoJson*
    object
    type*
    enum:string
    Will always be: FeatureCollection
    features*
    array: object
    id
    string
    type*
    enum:string
    Will always be: Feature
    properties*
    object
    stroke
    anyOf
    0
    string
    1
    object
    color
    string
    lineWidth
    number
    stroke-width
    number
    fill
    anyOf
    0
    string
    1
    object
    color
    string
    opacity
    number
    fill-opacity
    number
    geometry*
    one of
    0*
    object
    coordinates*
    array: array
    type*
    enum:string
    Will always be: Polygon
    1*
    object
    coordinates*
    array: array
    type*
    enum:string
    Will always be: LineString
    nodeId
    string
    3
    object
    type*
    enum:string
    Will always be: File
    format*
    enum:string
    Will always be: GeoJSON
    s3Id*
    string: UUID
    nodeId*
    string
    color
    object
    opacity
    object
    stroke
    object
    areaStatsReps
    object
    grossFloorPolygonsV2
    array: object
    grossFloorPolygon*
    array: array
    elevation*
    number
    areaType
    string
    buildingFloors3DSketch_UNSTABLE
    object
    gfaUnits
    array
    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
    Note that either all children must have keys specified or none of them
    id*
    string
    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

    Max length: 40

    * Required

    Response

    HTTP Status Code Summary

    200
    OK
    Reference to the root of the newly created element tree
    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 (200)

    urn
    string
    id
    string
    revision
    string

    Example

    Reference to the root of the newly created element tree

    Request

    curl -v 'https://developer.api.autodesk.com/forma/integrate/v1alpha/elements/:elementId?authcontext=pro_123' \
      -X 'POST' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
      -H 'Content-Type: application/json' \
      -d '{
            "rootElement": "",
            "elements": {}
          }'
    
    Show More

    Response

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