Request

Response

    Create a new element
    POST

    v2alpha/elements

    To store a representation you need to first upload it to S3 by using the upload link endpoint. The blobId retrieved in that endpoint can then be used in the representation.

    The desired element URNs can optionally be specified.

    Resource Information

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

    Request

    Body Structure

    Expand all
    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

    * 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?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"
    }