Request

Response

    Lists parameter specs.
    GET

    v1/specs

    By default, lists parameter specs used in the system. Specs define data types and describe, for example, how data is stored and presented to the user. For more information about the definition of specs, please refer to the Field Guide. For this endpoint, the user (authorization token) does not need access to a given Forma hub.

    If you provide a Forma hub ID in the request, the endpoint will return the user-defined specs to support enumerations. If you provide the Spec ID(s) in the request, the endpoint will return the Spec(s) with the provided ID(s). When using this endpoint with an Forma hub ID, the user must have access to the given Forma hub.

    Resource Information

    Method and URI
    GET
    https://developer.api.autodesk.com/parameters/v1/specs
    Authentication Context
    user context required
    Required OAuth Scopes
    data:read
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow.
    Region
    string
    The region the hub’s data is provisioned in. Currently supports US, EMEA, AUS, IND, DEU, JPN, CAN, and GBR. Default is US.
    * Required

    Request

    Query String Parameters

    accountId
    string: UUID or string: b.UUID
    The Autodesk Forma hub ID. If not provided, will return specs used by the system. If provided, will return the user defined specs to support enumerations.
    ids
    string
    The Spec ID(s) that you would like to return, split by a comma. Providing no Spec ID will return all user-defined Specs in the Forma hub.
    offset
    int
    Offset from the start of the collection to the first entry in the page. Zero based.
    limit
    int
    Determines the maximum number of objects that MAY be returned. A query MAY return fewer than the value of limit due to filtering or other reasons.

    Note- To see what parameters are using an enumeration data type, use the Search Parameters API.

    Response

    HTTP Status Code Summary

    200
    OK
    Successful retrieval of the parameter specs used in the system.
    400
    Bad Request
    The request could not be understood by the server due to malformed syntax.
    401
    Unauthorized
    Request has not been applied because it lacks valid authentication credentials for the target resource.
    403
    Forbidden
    The server understood the request but refuses to authorize it.
    404
    Not Found
    The resource cannot be found.
    406
    Not Acceptable
    The server cannot produce a response matching the list of acceptable values defined in the request.
    410
    Gone
    Access to the target resource is no longer available.
    429
    Too Many Requests
    User has sent too many requests in a given amount of time.
    500
    Internal Server Error
    An unexpected error occurred on the server.
    503
    Service Unavailable
    Server is not ready to handle the request.

    Response

    Body Structure (200)

    Expand all
    pagination
    object
    The information for paginating records returned by the endpoint.
    offset
    int
    Offset from the start of the collection to the first entry in the page. Zero based.
    limit
    int
    Determines the maximum number of objects that MAY be returned. A query MAY return fewer than the value of limit due to filtering or other reasons.
    totalResults
    int
    The total number of results that match the query irrespective of limit.
    nextUrl
    string
    Link that will return the next page of data. If not included, this is the last page of data.
    results
    array: object
    id
    string
    The 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. Value Type IDs support version ranges. For more information about version ranges in specs, please refer to the Field Guide. Results are returned for the highest applicable Value Type Id version available.
    context
    string
    The value “single” indicates that the spec stores a single value. The value “array” indicates that the spec stores an array of values.
    createdBy
    string
    User that created the parameter.
    createdAt
    string
    A Time ISO 8601 Timestamp in UTC Timezone indicating when the parameter was created.

    Example

    Successful retrieval of the specs (200).

    Request

    curl -v 'https://developer.api.autodesk.com/parameters/v1/specs'
    

    Response

    {
      "results": [
        {
          "id": "autodesk.spec.aec.structural:linearMomentScale-2.0.0",
          "name": "Linear Moment Scale",
          "disciplineId": "autodesk.spec.discipline:structural-1.0.0",
          "applicableUnitIds": [
            "autodesk.unit.unit:feetPerKip-1.0.0",
            "autodesk.unit.unit:metersPerKilonewton-1.0.0"
          ],
          "storageUnitId": "autodesk.unit.unit:metersPerKilonewton-1.0.0",
          "valueTypeId": "Float64",
          "context": "single",
          "createdBy": "System Generated",
          "createdAt": "System Generated"
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 50,
        "totalResults": 1
      }
    }
    
    Show More
    curl -v 'https://developer.api.autodesk.com/parameters/v1/specs?accountId=b3aef626-f535-4c7a-a032-c1048416f5ea'
        -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
    

    Response

    {
      "results": [
        {
          "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:4abfb8015fc34e17816b64abe0522864-14.0.0",
          "name": "Multiple Select: Lunch Order Items",
          "disciplineId": "autodesk.spec:discipline-2.0.0",
          "applicableUnitIds": null,
          "storageUnitId": null,
          "valueTypeId": "parameters.b3aef626f5354c7aa032c1048416f5ea:ba31c7ca1b7842e282211830d7f6f5a7-17.0.0",
          "context": "array",
          "createdBy": "FXA2K4JGR5BECGSF",
          "createdAt": "2024-11-05T18:55:42+0000",
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 50,
        "totalResults": 1
      }
    }
    
    Show More