Request

Response

    Field Guide

    This section describes the terms used in Parameters API.

    Overview

    Parameters API stores parameter data within a Forma hub. Today, the primary management experience is available through Autodesk Forma hub administration. Parameters are organized by two layers of grouping: the first level under the hub is called “groups”, and the second “collections”. Currently, a hub may contain only one “group”. (This feature is reserved for future enhancement.) Each “group” can have multiple collections. The image below depicts the structure.

    ../../../_images/Field_Guide_Diagram.png

    A “parameter” is defined by its name and data type, and typically has additional metadata, such as a category and labels.

    In the following, we explain each of these terms.

    Organizational Structure of Parameters: - Parameter Group - Collection - Parameter

    Composition of Parameter Metadata: - Spec - Unit - Label - Category - Classification Group

    Parameter group

    A parameter group is a set of collections typically united by the same purpose.
    Note: Currently only one group is supported and id is equal to hub id.
    id
    string: UUID
    The group ID.
    title
    string
    The group title.
    description
    string
    The group description.
    createdBy
    string
    The user who created the group.
    createdAt
    string
    The date that the group is created.
    updatedBy
    string
    The user who updated the group.
    updatedAt
    string
    The date that the group is updated.

    Relationships

    hub
    1-to-1
    parent hub for this parameter collection
    collections
    1-to-many
    parameters contained within the parameter collection

    Example Object

    {
      "id": "c23b5198ae2840a3a8ccc679903254c6",
      "title": "My Sample Group",
      "description": "This is my 1st sample group",
      "createdBy": "zlR4YAiokL302TZcopusRB0gHYBoaQGs",
      "createdAt": "2023-04-26T13:39:01+0000",
      "updatedBy": "WXE5QKQJUPV7",
      "updatedAt": "2023-04-27T04:27:57+0000"
    }
    
    Show More

    Parameter collection

    A parameter collection is a set of parameters typically united by the same purpose. A collection can represent any set of parameters that is convenient to your workflows.
    e.g. Hospital/ School / Airport Parameters / Parameters to share with door contractor / Parameters for a given project owner.
    Parameters should be created in your default collection and shared to other collections as needed, in order to match the current Parameters Service behavior.
    id
    string: UUID
    The collection ID.
    name
    string
    The collection name.
    permissions
    array: string
    The permissions of the user to access the parameters It could be read, write ,or admin.

    Relationships

    group
    1-to-1
    parent group for this parameter collection
    parameters
    1-to-many
    parameters contained within the parameter collection

    Example Object

    {
      "id": "02826a53ec-134b-0c98-0ab8-4af7a91214",
      "title": "Education Project Collection",
      "description": "Contains parameters for all education projects",
      "permissions": {
        "read": true,
        "write": false,
        "admin": false
      }
    }
    
    Show More

    Parameter

    A parameter is the definition of a granular value of a model element. This may be called differently by applications such as Parameter / Property / Attribute​.
    The id, name, specId and readOnly fields are the core definition of the parameter, which are immutable. The description and metadata could be changed by the Patch Parameters API.
    The core parameter definition can be retrieved by the Get Parameter. For this endpoint, the user (authorization token) does not need access to a given hub.
    The parameter description and metadata are stored in the hub and collection, they can be retrieved by the Retrieve Parameters.
    Expand all
    id
    string
    The parameter ID.
    name
    string
    The parameter name.
    description
    string
    The parameter description.
    specId
    string
    The parameter spec ID.
    readOnly
    boolean
    Indicates if the parameter is to be treated as read-only or not by a UI client. Immutable once set.
    metadata
    array: object
    The parameter metadata. It may vary from one product to another.
    For example, to support the use of a parameter in Revit, the metadata object might record category bindings and an instance/type assignment.
    anyOf
    0
    object
    An object with a string ID and a Boolean value. The ID could be one of the below:
    “isHidden” to indicate if the parameter is hidden or not in the application.
    “isArchived” to indicate if the parameter is archived or not.
    id
    string
    The metadata ID.
    value
    boolean
    Boolean value of the metadata.
    1
    object
    An object with a string ID and an enumerated string value. The ID could be “instanceTypeAssociation” to indicate if the parameter is associated with element instances, element types, or neither. Possible values: NONE, INSTANCE, TYPE
    id
    string
    The metadata ID.
    value
    string
    The metadata value.
    2
    object
    An object with a string ID and a string array value. The ID could be “labelIds” to list all the labels attached to this parameter.
    id
    string
    The metadata ID.
    value
    array: string
    The metadata value.
    3
    object
    An object with a string ID and an object value. The ID could be “group” to indicate the group for this parameter.
    id
    string
    The metadata ID.
    value
    object
    The metadata value.
    bindingId
    string
    The binding ID of the group, which can be looked up in the results of the GET /classifications/groups API.
    id
    string
    The group ID, which can be looked up in the results of the GET /classifications/groups API.
    4
    object
    An object with a string ID and an object array. The ID could be “categories” to indicate the categories of this parameter.
    id
    string
    The metadata ID.
    value
    array: object
    The metadata value.
    bindingId
    string
    The category binding ID, which can be looked up in the results of the GET /classifications/categories API.
    id
    string
    The category ID, which can be looked up in the results of the GET /classifications/categories API.
    5
    object
    An object with a string ID and a string value. The ID could be “specCategoryId” to indicate the spec category ID of this family type parameter.
    id
    string
    The metadata ID.
    value
    string
    The metadata value.

    Relationships

    parameter collection
    1-to-1
    parent parameter collection for this parameter
    spec
    1-to-1
    spec for the parameter
    label
    1-to-many
    labels attached to this parameter
    category
    1-to-many
    categories bind to this parameter
    group
    1-to-1
    group bind to this parameter

    Example Object

    {
      "id": "parameters.d05ec054ef8046ad9c80fc742f29027c:000ccf6716504165b73d20739f7dc1bf-1.0.0",
      "name": "ArtificialLighting",
      "description": ""
      "specId": "autodesk.spec:spec.string-2.0.0",
      "readOnly": false,
      "metadata": [
        {
          "id": "isHidden",
          "value": false
        },
        {
          "id": "isArchived",
          "value": false
        },
        {
          "id": "labelIds",
          "value": [
            "ACSF-01105-DTLK-44382",
            "ADJH-96226-GAKC-59763",
            "ACSY-84419-DPLC-36868"
          ]
        },
        {
          "id": "group",
          "value": null
        },
        {
          "id": "instanceTypeAssociation",
          "value": "TYPE"
        },
        {
          "id": "categories",
          "value": [
            {
              "bindingId": "ACFT-94219-HCEE-04771",
              "id": "autodesk.revit.category.family:doors-1.0.0"
            }
          ]
        },
        {
          "id": "specCategory",
          "value": null
        }
      ]
    }
    
    Show More

    Spec

    A spec describes a data type for user-facing presentation. Specs assist in specifying custom properties in design applications, so that end users may select the correct data type for a property. Examples of spec objects: Text, Yes/No, Image, Length, or Thermal Resistance. A spec can be used to create a single or multiple select datatype for parameters when specifying an enumeration.

    A spec object includes the following fields:

    id
    string
    The parameter spec ID.
    name
    string
    The user-facing name of the spec.
    disciplineId
    string
    The discipline ID. Look up detailed information in the response of the GET /disciplines API.
    applicableUnitIds
    array: string
    The identifiers of the units applicable to this spec. This field exists only for measurable specs that are associated with units of measurement, such as “Length” or “Acceleration”. It is null for non-measurable specs such as “Text” or “Yes/No”.
    storageUnitId
    string
    The identifier of the storage unit of this spec. This field exists only for measurable specs that are associated with units of measurement, such as “Length” or “Acceleration”. It is null for non-measurable specs such as “Text” or “Yes/No”. The storage unit is the unit of measurement that quantifies values of this parameter in persistent storage. When writing parameter values, client applications must ensure that the values written are quantified according to each parameter’s storage unit. A unit conversion might be necessary if input values are quantified differently.
    valueTypeId
    string
    The identifier of the storage value type, which could be Bool, Int64, Float64, Reference, String or a type ID. Using an enumeration type ID will allow you to define a custom data type using an enumeration.
    context
    string
    For enumerations only. The intended use of the spec in a list, to pick a single value or multiple values from the enumeration.

    Specs allow version ranges to be defined for a valueTypeId. This allows enumerations to be updated and parameters using the spec will be able to get new data without changing the parameter’s version as well.

    It is possible to specify a range of valid versions for a property. This may be valuable to allow some flexibility without introducing breaking changes.

    Use >= to denote that you would like to accept any version greater than or equal to the specified version. For Example - “typeId”: “a.a:a->=1.0.1” would accept any version greater than or equal to 1.0.1.

    Use ^ to denote that you would like to accept any version greater than or equal to the specified version, as long as it has the same major number. For Example - “typeId”: “a.a:a-^1.0.1” would accept any version greater than or equal to 1.0.1, but less than 2.0.0.

    Use ~ to denote that you would like to accept any version greater than or equal to the specified version, as long as it has the same major and minor number. For Example - “typeId”: “a.a:a-~1.0.1” would accept any version greater than or equal to 1.0.1, but less than 1.1.0.

    Relationships

    parameter
    1-to-1
    the parameter using this spec
    discipline
    1-to-1
    the discipline for this spec
    unit
    1-to-many
    the units associated with this spec
    enumeration
    1-to-1
    the enumeration used by this spec, if used as the spec’s valueTypeId

    Example Object

    {
      "id": "autodesk.spec.aec.electrical:apparentPower-2.0.0",
      "name": "Apparent Power",
      "disciplineId": "autodesk.spec.discipline:electrical-1.0.0",
      "applicableUnitIds": [
          "autodesk.unit.unit:watts-1.0.1",
          "autodesk.unit.unit:kilowatts-1.0.1",
          "autodesk.unit.unit:britishThermalUnitsPerSecond-1.0.1",
          "autodesk.unit.unit:britishThermalUnitsPerHour-1.0.1",
          "autodesk.unit.unit:caloriesPerSecond-1.0.1",
          "autodesk.unit.unit:kilocaloriesPerSecond-1.0.1",
          "autodesk.unit.unit:voltAmperes-1.0.1",
          "autodesk.unit.unit:kilovoltAmperes-1.0.1",
          "autodesk.unit.unit:horsepower-1.0.1"
      ],
      "storageUnitId": "autodesk.unit.unit:watts-1.0.1"
    }
    
    Show More

    Enumeration

    An enumeration describes a user-defined list for creating specs that facilitate the single or multiple selection data type. Enumerations assist in specifying a custom list of options/values for a parameter to use. An enumeration object includes the following fields:

    id
    string
    The enumeration ID.
    name
    string
    The user-facing name of the enumeration.
    content
    map
    A map of IDs and values for available options in the list. Look up detailed information in the response of the GET /enumerations API.

    Relationships

    spec
    1-to-many
    the specs using this enumeration

    Example Object

    {
      "id": "parameters.d05ec054ef8046ad9c80fc742f29027c:61712b031b1e49e897e3cf1643dea73f-2.0.0",
      "name": "Streetlight Colors",
       "Content": [
           {
                      "id": "Red",
                      "value": 0
                  },
                  {
                      "id": "Yellow",
                      "value": 1
                  },
                  {
                      "id": "Green",
                      "value": 2
                  }
            ],
                  "createdBy": "FXA2K4JGR5BECGSR",
                  "createdAt": "2024-11-11T16:22:29+0000"
            },
    }
    
    Show More

    Unit

    A unit defines a standard representation of units and formatting rules.

    id
    string
    The unit ID.
    name
    string
    The unit name.
    symbolIds
    array: string
    The identifiers of symbols that indicate this unit in a written measurement, such as the “m” indicating “meters” in a written measurement such as “5m”. A unit of measurement may have zero, one, or many symbols available. Symbols may be used when rendering parameters.

    Relationships

    spec
    1-to-1
    the parent spec
    symbol
    1-to-many
    all the symbols of the unit

    Example Object

    {
      "id": "autodesk.unit.unit:feet-1.0.1",
      "name": "Feet",
      "symbolIds": [
          "autodesk.unit.symbol:feetAndInches-1.0.1",
          "autodesk.unit.symbol:footSingleQuote-1.0.1",
          "autodesk.unit.symbol:ft-1.0.1",
          "autodesk.unit.symbol:lf-1.0.1"
      ]
    }
    
    Show More

    Label

    A label is a meta-data that is attached to specific parameter that help search and filter parameters

    id
    string
    The label ID.
    name
    string
    The label name.
    description
    string
    The label description.

    Relationships

    parameters
    1-to-many
    the parameters attached with the label.

    Example Object

    {
      "id": "ACMT-69415-CEVT-22201",
      "name": "test",
      "description": ""
    }
    

    Category

    A category controls the organization, visibility, graphical representations, and scheduling options of Families within the Project.

    id
    string
    The category ID.
    name
    string
    The category name.
    disciplineIds
    array: string
    The discipline IDs of this category. Look up detailed information in the response of the GET /disciplines API.
    parentCategoryId
    string
    The parent category ID of this category.
    bindingId
    string
    The bindingId of this this category. It is used to create the parameters with categories, which will help to organize the parameters in different categories in the application, like Revit. The category can’t be bound to any parameters if the bindingId is null.

    Relationships

    parameter
    1-to-1
    the parameter associated with this category
    discipline
    1-to-many
    the disciplines for this category

    Example Object

    {
      "id": "autodesk.revit.category.family:fireProtection-1.0.0",
      "name": "Fire Protection",
      "disciplineIds": [
        "autodesk.spec.discipline:architecture-1.0.0",
        "autodesk.spec.discipline:structural-1.0.0",
        "autodesk.spec.discipline:hvac-1.0.0",
        "autodesk.spec.discipline:electrical-1.0.0",
        "autodesk.spec.discipline:piping-1.0.0",
        "autodesk.spec.discipline:infrastructure-1.0.0"
      ],
      "parentCategoryId": null,
      "bindingId": "ACFT-94213-BNDF-85095"
    }
    
    Show More

    Classification Group

    A classification group helps to organize the parameters in the application, like Revit property pallet group.

    id
    string
    The classification group ID.
    name
    string
    The classification group name.
    bindingId
    string
    The binding ID of this group. It is used to create parameters with group binding, which will help to organize the parameters in different groups in the application, like Revit. The group can’t be bound to any parameters if the bindingId is null.

    Relationships

    parameter
    1-to-1
    the parameter associated with this group

    Example Object

    {
      "id": "autodesk.parameter.group:adskModelProperties-1.0.0",
      "name": "Model Properties",
      "bindingId": "ABXZ-68714-GYLB-48622"
    }
    

    Limitations

    The following list details known limitations of the current release of the Parameters API:

    • Search APIs will return a (200) response even if it returns with errors in the response instead of a (207)
    • Attach Labels API will return a (201) response even if it returns with errors in the response instead of a (207)
    • Detach Labels API will return a (204) response even if it returns with errors in the response instead of a (207)
    • Update or Detach Labels APIs can update parameters outside the specified collection in certain instances.