Request

Response

    Updates specs.
    PUT

    v1/specs:batch-update

    Updates a list of specs (maximum amount per request is 10) with the latest version of the enumeration used in the spec.

    Resource Information

    Method and URI
    PUT
    https://developer.api.autodesk.com/parameters/v1/specs:batch-update
    Authentication Context
    user context required
    Required OAuth Scopes
    data:create or data:write
    Data Format
    JSON

    Note: Data will be updated according to the JSON Merge Patch protocol.

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow.
    Content-Type*
    string
    Must be application/json
    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.
    * Required

    Request

    Body Structure

    Object

    Expand all
    specs*
    array: object
    The list of specs to update.
    id*
    string
    The spec ID. Must be full type id.
    * Required

    Response

    HTTP Status Code Summary

    200
    OK
    Successfully updated the given specs.
    207
    Partial Success
    Successfully updated some specs, with errors for some specs in the batch.
    400
    Bad Request
    The request could not be understood by the server due to malformed syntax. This may occur when specs validation fails, such as when the specs name is too long or contains prohibited symbols. The response should include what validation rule was violated.
    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

    Successfully Updated Specs (200)

    Body Structure (200)

    Expand all
    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.
    content
    array: object
    The spec content. Provided only for specs with enumeration value types, this field contains the body of the enumeration as a map with keys of type string and values of type number.
    id
    string
    The enumeration ID for a single item in the list.
    value
    number
    The enumeration value for a single item in the list.
    createdBy
    string
    User that created the spec.
    createdAt
    string
    A Time ISO 8601 Timestamp in UTC Timezone indicating when the spec was created.

    Partial Success Updating Specs (207)

    Body Structure (207)

    Expand all
    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.
    content
    array: object
    The spec content. Provided only for specs with enumeration value types, this field contains the body of the enumeration as a map with keys of type string and values of type number.
    id
    string
    The enumeration ID for a single item in the list.
    value
    number
    The enumeration value for a single item in the list.
    createdBy
    string
    User that created the spec.
    createdAt
    string
    A Time ISO 8601 Timestamp in UTC Timezone indicating when the spec was created.
    errors
    array: object
    id
    string
    The resource ID.
    title
    string
    The error title.
    detail
    string
    The error detail.
    code
    string
    The error code.

    Example

    Successfully Updated Specs (200).

    Request

    curl -v 'https://developer.api.autodesk.com/parameters/v1/specs:batch-update' \
      -X 'PUT' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
      -H 'Content-Type: application/json' \
      -d '{
            "specs": [
              {
                "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:d8cf6d9ae20d4775b1a246399d4ff48a-1.0.0"
              },
              {
                "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:8bb37d61b3dc489aa94d6bac3d88038c-1.0.0"
              }
            ]
          }'
    
    Show More

    Response

    {
       "results": [
           {
               "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:d8cf6d9ae20d4775b1a246399d4ff48a-2.0.0",
               "name": "Single Select: some spec",
               "valueTypeId": "parameters.b3aef626f5354c7aa032c1048416f5ea:61712b031b1e49e897e3cf1643dea73e-2.0.0",
               "context": "single",
               "createdBy": "FXA2K4JGR5BECGSR",
               "createdAt": "2024-11-11T16:22:31+0000",
               "disciplineId": "autodesk.spec:discipline-2.0.0",
               "applicableUnitIds": null,
               "storageUnitId": null,
               "content": [
                   {
                       "id": "item11",
                       "value": 0
                   },
                   {
                       "id": "item2",
                       "value": 1
                   }
               ],
               "previousRevisionId": "parameters.b3aef626f5354c7aa032c1048416f5ea:d8cf6d9ae20d4775b1a246399d4ff48a-1.0.0"
           },
           {
               "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:8bb37d61b3dc489aa94d6bac3d88038c-2.0.0",
               "name": "Multiple Select: some spec",
               "valueTypeId": "parameters.b3aef626f5354c7aa032c1048416f5ea:61712b031b1e49e897e3cf1643dea73e-2.0.0",
               "context": "array",
               "createdBy": "FXA2K4JGR5BECGSR",
               "createdAt": "2024-11-11T16:22:31+0000",
               "disciplineId": "autodesk.spec:discipline-2.0.0",
               "applicableUnitIds": null,
               "storageUnitId": null,
               "content": [
                   {
                       "id": "item11",
                       "value": 0
                   },
                   {
                       "id": "item2",
                       "value": 1
                   }
               ],
               "previousRevisionId": "parameters.b3aef626f5354c7aa032c1048416f5ea:8bb37d61b3dc489aa94d6bac3d88038c-1.0.0"
           }
       ]
    }
    
    Show More

    Partial Success Updating Specs (207).

    Request

    curl -v 'https://developer.api.autodesk.com/parameters/v1/specs:batch-update' \
      -X 'PUT' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
      -H 'Content-Type: application/json' \
      -d '{
            "specs": [
              {
                "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:fe82bd1dbfa64a6fae5ee14f6171301b-1.0.0"
              },
              {
                "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:9dbcf4dca2e74edeb4faec744f0b7aa8-1.0.0"
              }
            ]
          }'
    
    Show More

    Response

    {
       "results": [
           {
               "id": "parameters.d05ec054ef8046ad9c80fc742f29027c:9dbcf4dca2e74edeb4faec744f0b7aa8-1.0.1",
               "name": "Multiple Select: some spec12",
               "valueTypeId": "parameters.b3aef626f5354c7aa032c1048416f5ea:a644eb8695914628a259fd5a3b37f622-2.0.2",
               "context": "array",
               "createdBy": "FXA2K4JGR5BECGSR",
               "createdAt": "2024-11-19T19:47:48+0000",
               "disciplineId": "autodesk.spec:discipline-2.0.0",
               "applicableUnitIds": null,
               "storageUnitId": null,
               "content": [
                   {
                       "id": "item11",
                       "value": 0
                   },
                   {
                       "id": "item2",
                       "value": 1
                   }
               ],
               "previousRevisionId": "parameters.d05ec054ef8046ad9c80fc742f29027c:9dbcf4dca2e74edeb4faec744f0b7aa8-1.0.0"
           }
       ],
       "errors": [
           {
               "code": "SPEC-INVALID-SPEC",
               "title": "Bad request",
               "detail": "The Spec with the given ID does not exist",
               "id": "parameters.b3aef626f5354c7aa032c1048416f5ea:fe82bd1dbfa64a6fae5ee14f6171301b-1.0.0"
           }
       ]
    }
    
    Show More