{ "openapi" : "3.0.1", "info" : { "contact" : { "email" : "info@topdesk.com", "name" : "TOPdesk", "url" : "http://www.topdesk.com" }, "description" : "This API provides endpoints for defining, modifying and accessing customer-specific business resources. The Asset Management API supports adding arbitrary number of fields and widgets to these and also supports defining basic relationship rules between them.\n\nThe term 'asset' represents any business resource in the broader sense. They are grouped into 'categories' - by the 'resourceCategory' property - based on their major traits, which may differ substantially for tangible entities and abstract resource definitions. Resource categories define rules, introduce restrictions, but they also provide access to additional APIs specific for them. Basically all Asset Management endpoints can be used for all resource categories, taking the pre-defined restrictions into consideration.\n\nCurrently the following resource categories are supported:", "title" : "Asset Management REST API", "version" : "v1.91.3" }, "servers" : [ { "url" : "https://{topdesk_host}/tas/api/assetmgmt", "variables" : { "topdesk_host" : { "default" : "customer.topdesk.net" } } } ], "tags" : [ { "description" : "Creating, modifying, reading and deleting business resources a.k.a 'assets'. Note, that these endpoints can be used for any resource categories, for example 'stocks'.", "name" : "Assets" }, { "description" : "Business resources can be linked together using 'link types'. Pre-defined link types are available, but new ones can be defined by users.", "name" : "Asset links" }, { "description" : "Assets can be linked together using link types. Please note that for backward compatibility reasons the old term 'capability' is used instead of 'link type' throughout the API.", "name" : "Link Types" }, { "description" : "Assets can be assigned to various kinds of entities of TOPdesk.", "name" : "Assignments" }, { "description" : "An asset consists of dynamically defined fields.", "name" : "Fields" }, { "description" : "Assets are defined by templates. A template describes a structure which is specific to a particular asset type.", "name" : "Templates" }, { "description" : "API for uploading and downloading binary data regarding assets.", "name" : "Uploads" }, { "description" : "API for querying and editing quantity information about bulk items on stock and for managing links between these two types of resources.", "name" : "Stock Quantities" }, { "description" : "This sub-API is designed to be used by TOPdesk's Asset Management Import feature, but is available for general use.", "name" : "Asset Management Import API" } ], "paths" : { "/assetLinks" : { "get" : { "description" : "Returns a list of assets that are linked to the specified asset provided as a parameter (sourceId). When *sourceId* and *targetId* are both provided then the direction of the link is also matched.\n\nThe list will include the following information about the linked assets: the name, ID, type and properties of the icon of the asset; the type and ID of the link; ID and name of the used link type.", "operationId" : "getLinkedAssets", "parameters" : [ { "description" : "The ID of the source asset. It can also identify the target asset, but only when *targetId* is not provided.", "in" : "query", "name" : "sourceId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the target asset.", "in" : "query", "name" : "targetId", "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the link type used to link the resulting assets to the source asset.", "in" : "query", "name" : "capabilityId", "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/LinkedAsset" } } } }, "description" : "successful operation" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Return linked assets.", "tags" : [ "Asset links" ] }, "post" : { "description" : "Creates a link between two assets. These links are often referred to as 'relationships'.\n\nWhen creating a link, you need to specify the two assets you want to link (sourceId, targetId), and the desired relationship between them. To get the available types of relationship between the two assets, use the /assetmgmt/assetLinks/possibleRelations endpoint.", "operationId" : "link", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssetLinkRequest" } } }, "description" : "Specification of the new link.", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkedAsset" } } }, "description" : "successful operation" }, "400" : { "description" : "When the request is invalid or the link exists already." }, "403" : { "description" : "When user doesn't have 'write' permission for the asset type." } }, "summary" : "Link asset to target asset.", "tags" : [ "Asset links" ] } }, "/assetLinks/possibleRelations" : { "get" : { "description" : "Returns the available relationship types (child, parent and available link type IDs) for two assets (sourceId, targetId).\n\nIf the specified two assets are already linked in every possible way, then the result will be empty.\n\nThis endpoint is the most beneficial if you use it before creating a new link between two assets.", "operationId" : "possibleRelations", "parameters" : [ { "description" : "The ID of the source Asset", "in" : "query", "name" : "sourceId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the target Asset", "in" : "query", "name" : "targetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { "type" : "string" } } } }, "description" : "successful operation" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Return the list of possible relations between source and target asset", "tags" : [ "Asset links" ] } }, "/assetLinks/{relationId}" : { "delete" : { "operationId" : "unlink", "parameters" : [ { "description" : "The ID of the relation", "in" : "path", "name" : "relationId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkedAsset" } } }, "description" : "Successfully removed link" }, "403" : { "description" : "When user doesn't have 'write' permission for the asset type." } }, "summary" : "Remove link between two assets", "tags" : [ "Asset links" ] } }, "/assetStatuses" : { "get" : { "description" : "Returns a list of all asset statuses. By default, only the ID of each option is included. To also include the translated display name, use \"field=name\" as a query parameter in the URL.

\n| Permission | Remarks |\n| --- | --- |\n| Operator | Unrestricted access |\n| Person | No access |", "operationId" : "getAssetStatusValues", "parameters" : [ { "in" : "query", "name" : "field", "schema" : { "type" : "array", "items" : { "type" : "string" } } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssetStatusResults" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:" } }, "summary" : "Returns a list of all asset statuses.", "tags" : [ "Asset Management Import API" ] } }, "/assets" : { "get" : { "description" : "Returns a list of assets. By default the following fields are included: id, name (text), etag and state (archived). You can use various parameters to filter this list or to retrieve other fields from the assets.\n\nBranch filters are applied to the assets, as well as to their (person, person group, branch, location) assignments in the response.\n\n⚠️**Deprecation warning**: the `application/x.topdesk-am-assets-v1+json` media type is deprecated and is going to be removed in a future release. As a consequence, the \"type\" and the \"icon\" property of objects in the \"dataSet\" array won't be included in the response unless requested. Currently, their value is the name and the icon of the template, respectively. We strongly recommend setting the Accept header of each request to `application/x.topdesk-am-assets-v2+json` in order to get the new version of the assets resource and to follow the best practice of depending on a specific resource version explicitly. With the new version, the value of the \"type\" and the \"icon\" property changes to the value of the corresponding user-defined fields, if they exist, otherwise it changes to \"null\". To retrieve the name or the icon of the template, read the \"name\" and the \"icon\" properties of the \"@type\" object within \"dataSet\" items, respectively.\n\nTimeline:\n- After the end of April, 2024, support for the `application/x.topdesk-am-assets-v1+json` media type is going to be dropped entirely.", "operationId" : "getAssets", "parameters" : [ { "description" : "Filters assets by checking whether their name contains this search term. Matching is case insensitive. Special and whitespace characters are supported without the need to escape them. An empty value matches all assets.", "in" : "query", "name" : "nameFragment", "schema" : { "type" : "string" } }, { "description" : "To filter assets by their name-fragment or any fragment in their text or number type fields. It's case-insensitive.", "in" : "query", "name" : "searchTerm", "schema" : { "type" : "string" } }, { "description" : "To filter assets by a specific template. Since each asset type uses only one template, this filtering is the same as filtering by asset types.", "in" : "query", "name" : "templateId", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "To filter assets by a specific template's name (case sensitive).", "in" : "query", "name" : "templateName", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Whether to include template information in the response. It can be one of the following: none (default if omitted), relevant (works only if linkedTo is present), all.", "in" : "query", "name" : "includeTemplates", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Whether to show archived assets. Leave out for all, or specify true/false for only archived, or only active assets, respectively.", "in" : "query", "name" : "archived", "schema" : { "type" : "boolean" } }, { "description" : "Specifies the set of returned asset fields and auxiliary asset information. Field names are to be provided as a comma-separated list of the same query parameter. The specified pieces of information are returned inside the 'dataSet' array. Additional meta-data about the requested fields (like their type and display name) is returned in the 'columns' array of the response. Possible values are the following:", "in" : "query", "name" : "fields", "schema" : { "type" : "string" } }, { "description" : "When it's given it returns more meta information, including all person and location related assignments. See '/assignments' endpoint documentation for more details about the response format.", "in" : "query", "name" : "showAssignments", "schema" : { "type" : "boolean" } }, { "description" : "Entity type and ID of the entity the assets are linked to, separated by a slash character. Accepted types: assignable types (person, personGroup, branch, location) and external link types (incident, changeActivity, knowledge, change, problem, omActivity, omSeries, service).\n- Example: `linkedTo=person/4878f620-e404-4f2d-9d53-622a1693d467`.\n- Instead of an ID, wildcards can also be used with certain types. In that case, and only then, multiple type/value pairs are also accepted, which should be separated by a comma.\n * Supported wildcards are:\n - 'any' for any active or archived entities. Supported for the following types: person, personGroup, branch, location, service.\n - 'anyArchived' for any archived entities. Supported for the following types: person, personGroup.\n * Example: `linkedTo=person/any,personGroup/anyArchived`. This filters for assets that are linked to any person or linked to any archived person group.\n- At most one type/value pair can be specified when the type is an external link type, and it cannot be combined with assignable types.", "in" : "query", "name" : "linkedTo", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Entity type and ID of the entity the assets are *not* linked to, separated by a slash character. Accepted types are the same as for linkedTo.\n- Example: `notLinkedTo=person/4878f620-e404-4f2d-9d53-622a1693d467`.\n- Instead of an ID, wildcards can also be used with certain types. In that case, and only then, multiple type/value pairs are also accepted, which should be separated by a comma.\n * Supported wildcards are:\n - 'any' for any active or archived entities. Supported for the following types: person, personGroup, branch, location.\n - 'anyArchived' for any archived entities. Supported for the following types: person, personGroup.\n * Example: `notLinkedTo=person/any,personGroup/anyArchived`. This filters for assets that are not linked to any person or not linked to any archived person group.\n- At most one type/value pair can be specified when the type is an external link type, and it cannot be combined with assignable types.\n", "in" : "query", "name" : "notLinkedTo", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Used together with linkedTo or notLinkedTo parameters. Whether to filter assets by including inherited assignments.\n\nFor example:", "in" : "query", "name" : "filterInherited", "schema" : { "type" : "boolean", "default" : true } }, { "description" : "To filter assets by their status. Possible values: OPERATIONAL, IMPACTED.", "in" : "query", "name" : "assetStatus", "schema" : { "type" : "string" } }, { "description" : "Supports a set of OData filters which can be combined with 'and' and 'or' operators. Filter expressions can also be grouped by parentheses.\n- Filtering based on the name field with greater-than operator. Example: `$filter=name gt 'CAR0042'`.\n- Filtering based on the templateId field. Supported operators: eq, in, ne. Example: `$filter=templateId eq 'fc886aa0-8315-4ff9-b7f9-ad79a01d5f5c' and templateId eq '3c5f3383-23d5-40bf-95f0-78b151c028ea'`.\n- Filtering based on the ID of the reason for archiving. Supported operators: eq, in. Example: `$filter=archiveReason in ['add003d1-d7e1-4776-8d1d-ebc79864fc68', 'e5437db1-0ea9-412b-948f-c38f5b2ce425']`.\n- Filtering based on date fields with greater-than, less-than, greater-than-or-equals, less-than-or-equals, equals, and non-equals operators. Example: `$filter=modificationDate gt '2017' and modificationDate lt '2017-05-26'`.\n * Dates are interpreted as UTC dates.\n * Supported formats: yyyy (2017); yyyy-MM (2017-12); yyyy-MM-dd (2017-12-25); yyyy-MM-dd'T'HH:mm (2017-12-25T18:30); yyyy-MM-dd'T'HH:mm:ss (2017-12-25T18:30:12); yyyy-MM-dd'T'HH:mm:ss.SSS (2017-12-25T18:30:12.798). When hours, minutes or seconds are omitted, they are considered to be 0. When month is omitted it's considered to be January. When day is omitted, it's considered to be '1'.\n * The following relative date ranges are also supported with `eq` and `ne` operator: `lastYear`, `thisYear`, `nextYear`, `lastMonth`, `thisMonth`, `nextMonth`, `lastWeek`, `thisWeek`, `nextWeek`, `yesterday`, `today`, `tomorrow`. These intervals are meant to be in the server's current time and time zone. First day of the week is considered to be 'Sunday'.\n- Filtering based on a linked entity. Example: `$filter=linkedTo eq 'incident/2eebf650-c5d7-4bf3-ad05-1f4cbced3b06'`. Note, that this filter can be also expressed by the more flexible 'isLinkedTo' function. Possible external link types are: incident, changeActivity, knowledge, change, problem, omActivity, omSeries, service. Currently external link types other than 'service' are not supported when combining filters with the ‘or’ operator, or as part of nested filters.\n- Filtering based on linked assets: `isLinkedTo(, , )`. For the meaning and usage of the three function arguments check `linkedToAsset`, `linkedWithCapability`, and `linkedWithDirection` query parameters. The function must have three arguments but `` can be null. Examples:\n * Assets that are linked to a specific asset with a specific link type and direction (source): `isLinkedTo('e08dcc19-8008-436e-82f1-c99b1cf9d727', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'source')`\n * Assets that are linked to a specific asset with a specific link type and direction (target): `isLinkedTo('e08dcc19-8008-436e-82f1-c99b1cf9d727', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'target')`\n * Assets that are linked to the given assets either as source or target: `isLinkedTo('e08dcc19-8008-436e-82f1-c99b1cf9d727', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'any')`\n * Assets that are not linked to the given asset as source neither as target: `isLinkedTo('e08dcc19-8008-436e-82f1-c99b1cf9d727', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'none')`\n * Assets that are linked to any asset with a specific link type and direction: `isLinkedTo('any', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'source')`\n * Assets that are not linked to any asset with a specific link type and direction: `isLinkedTo('none', '2eebf650-c5d7-4bf3-ad05-1f4cbced3b44', 'source')`\n * If `` is null, it means the default parent/child relationship: `isLinkedTo('e08dcc19-8008-436e-82f1-c99b1cf9d727', null, 'source')`\n- Filtering based on linked external entities are also supported by the `isLinkedTo()` function where the meaning of the parameters are the following: `isLinkedTo(, , )`.\n * For external entities `` is always null and `` is always 'source' or 'none'.\n * External entity ID's format: `service/2eebf650-c5d7-4bf3-ad05-1f4cbced3b06`.\n * Wildcards are supported only for 'services': `isLinkedTo('service/any', null, 'source')`,`isLinkedTo('service/none', null, 'source')`\n * Assets which are not linked to a specific service can be expressed like this: `isLinkedTo('service/2eebf650-c5d7-4bf3-ad05-1f4cbced3b06', null, 'none')`\n- Filtering based on a text field. Use the 'contains' operator. Example: `$filter=specification contains 'desk'`.\n- Filtering based on a checkbox field on false and true values. Example: `$filter=termsandconditions eq 'false'`.\n- Filtering based on a number field. Examples: `$filter=cost eq 15`, `$filter=cost ge 40`.\n- Filtering based on a dropdown field. Supported operators: eq, in, ne. Example: `$filter=dropdown-field eq '2eebf650-c5d7-4bf3-ad05-1f4cbced3b06'`.\n- Filtering based on whether a text, number, dropdown or date field is empty or not empty. Missing values and empty strings are considered empty. Fields that do not exist for a given type are considered neither empty nor not empty. Examples: `$filter=text-field isEmpty`, `$filter=text-field isNotEmpty`.\n- Filtering based on the id field with 'eq' or 'in' operator. Examples: `$filter=id eq 'e08dcc19-8008-436e-82f1-c99b1cf9d727'`, `$filter=id in ['e08dcc19-8008-436e-82f1-c99b1cf9d727','23c484cd-cdcf-48ae-a7bd-b655efb3c686']`. Combining this kind of filter with others using the ‘or’ operator, or creating nested filters of it are not supported.", "in" : "query", "name" : "$filter", "schema" : { "type" : "string" } }, { "description" : "OData like ordering on assets based on the value of a *single field* specified by this parameter. Secondary ordering is always performed by name. Sorting direction needs to be set to either *asc* or *desc*. Currently, sorting can be based on the following types of fields: text (including name and @@summary), date (including modificationDate and creationDate), number, boolean, and dropdown with own options.", "example" : "modificationDate desc", "in" : "query", "name" : "$orderby", "schema" : { "type" : "string", "default" : "name asc" } }, { "description" : "Can be used for implementing seek-based paging. Skips assets whose name precedes or equals to the value of this parameter according to the sorting direction. Can be used together with *lastSeenOrderbyValue* and *$orderby*. If *lastSeenOrderbyValue* is not present, using this parameter leads to a bad request error.\n\nNote: Using this parameter is only supported when *$orderby* is set to either name, @@summary, modificationDate, or creationDate.", "example" : "CAR0042", "in" : "query", "name" : "lastSeenName", "schema" : { "type" : "string" } }, { "description" : "Can be used for implementing seek-based paging. Skips assets that have a preceding value for the field specified in *$orderby* compared to the value of this parameter. In case of value equality the value of *lastSeenName* determines whether to skip an asset or not. Can be used together with *lastSeenName* and *$orderby*. When sorting is based on the name only, the value of this parameter should be the same as the value of *lastSeenName*. If *lastSeenName* is not present, using this parameter leads to a bad request error.\n\nNote: Using this parameter is only supported when *$orderby* is set to either name, @@summary, modificationDate, or creationDate.", "example" : "2020-02-02T20:02:20.020", "in" : "query", "name" : "lastSeenOrderbyValue", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkableWithDirection* and optionally with *linkableWithCapability*. To filter assets by checking if they can be linked to the asset specified by its unique ID. An asset cannot be linked to itself. The same link cannot be applied multiple times. If *linkableWithDirection* is not provided, using this parameter results in a 'Bad Request' error. If *linkableWithCapability* is not provided, resulting assets are linkable without a link type.", "in" : "query", "name" : "linkableToAsset", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkableToAsset* and optionally with *linkableWithCapability*. To filter assets by direction. Possible values: SOURCE, TARGET.\n\nSOURCE: *linkableToAsset* can be the parent of results.\n\nTARGET: *linkableToAsset* can be the child of results.\n\nIf *linkableToAsset* is not provided, using this parameter results in a 'Bad Request' error. If *linkableWithCapability* is not provided, resulting assets are linkable without a link type.", "in" : "query", "name" : "linkableWithDirection", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkableWithDirection* and *linkableToAsset*. To filter assets by a link type specified by its unique ID. If either *linkableWithDirection* or *linkableToAsset* is not provided, using this parameter results in a 'Bad Request' error.", "in" : "query", "name" : "linkableWithCapability", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkedWithDirection* and optionally with *linkedWithCapability*. To filter assets by checking if they are linked to the asset specified by its unique ID. If *linkedWithDirection* is not provided, using this parameter results in a 'Bad Request' error. If *linkedWithCapability* is not provided, resulting assets are linked without a link type. In addition to a unique ID of an asset, the following values are also valid for the parameter:\n- any: results in assets that are linked to any asset with the specified direction and link type.\n- none: results in assets that are not linked to any asset with the specified direction and link type. This value is supported for backward compatibility reasons, as the same effect can be achieved by using *linkedWithDirection=none* in combination with *linkedToAsset=any*. Setting both *linkedWithDirection* and *linkedToAsset* to *none* results in a 'Bad Request' error.", "in" : "query", "name" : "linkedToAsset", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkedToAsset* and optionally with *linkedWithCapability*. To filter assets by direction. Possible, case-insensitive values:\n- source: *linkedToAsset* can be the parent of results.\n- target: *linkedToAsset* can be the child of results.\n- any: *linkedToAsset* can be either the parent or the child of results.\n- none: *linkedToAsset* is not linked to the resulting assets.\n\nIf *linkedToAsset* is not provided, using this parameter results in a 'Bad Request' error. If *linkedWithCapability* is not provided, resulting assets are linked without a link type.", "in" : "query", "name" : "linkedWithDirection", "schema" : { "type" : "string" } }, { "description" : "Used together with *linkedWithDirection* and *linkedToAsset*. To filter assets by a link type specified by its unique ID. When left unspecified, the absence of a custom link type is assumed. In addition to a unique ID of a link type, 'any' is also a valid value. 'any' indicates that all link types match, including relationships without a link type. If either *linkedWithDirection* or *linkedToAsset* is not provided, using this parameter results in a 'Bad Request' error.", "in" : "query", "name" : "linkedWithCapability", "schema" : { "type" : "string" } }, { "description" : "The endpoint returns assets matching the specified category only.", "in" : "query", "name" : "resourceCategory", "schema" : { "type" : "string", "default" : "asset", "enum" : [ "asset", "stock", "bulkItem" ] } }, { "description" : "Show inherited assignments of assets.", "in" : "query", "name" : "includeInherited", "schema" : { "type" : "boolean", "default" : false } }, { "description" : "The number of assets to skip, or, in other words, the zero-based index of the asset to return as the first item of the requested page. In case the value is greater than or equal to the total number of retrieved assets the resulting list is empty. This parameter cannot be used together with either lastSeenName or lastSeenOrderbyValue, as they provide an alternative way of paging.", "in" : "query", "name" : "pageStart", "schema" : { "type" : "integer", "format" : "int64", "default" : 0, "example" : 16, "minimum" : 0 } }, { "description" : "The maximum number of assets to return in one page. Must be between 0 and 1000, both inclusive.", "in" : "query", "name" : "pageSize", "schema" : { "type" : "integer", "format" : "int64", "default" : 50, "example" : 42, "maximum" : 1000, "minimum" : 0 } }, { "deprecated" : true, "description" : "The maximum number of assets to return in one page. Must be a non-negative decimal number. If higher than 50 then it is treated as if the parameter was not set.\n\n⚠️This query parameter will be removed in the future as it is superseded by *pageSize*, the parameter that has a standard name across new APIs of TOPdesk and that supports fetching a significantly higher number of assets. Support for this parameter will end after April, 2025.", "in" : "query", "name" : "limit", "schema" : { "type" : "integer", "format" : "int64", "default" : 50, "example" : 32, "minimum" : 0 } }, { "description" : "Whether to include assets in the response or not.", "in" : "query", "name" : "fetchData", "schema" : { "type" : "boolean", "default" : true } }, { "description" : "Whether to include the asset count in the response or not. This parameter is especially useful if the number of assets is needed. With this solution, counting the assets on client side can be avoided, as the count is available in the `count` property of the response body.", "in" : "query", "name" : "fetchCount", "schema" : { "type" : "boolean", "default" : false } }, { "description" : "Whether to turn the value of dropdown fields into an object that contains the display name of options next to their ID. This could be useful when you want to avoid making many additional requests for retrieving display names, which can be performed on a per dropdown option basis like this: `GET /assets?templateId=&id=`. The 'id' and 'name' properties of the object are present with null value when the corresponding asset has no value for a particular dropdown field.", "in" : "query", "name" : "resolveDropdownOptions", "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-assets-v1+json;qs=0.5" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } }, "application/x.topdesk-am-assets-v2+json" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } } }, "description" : "When the query is successful and the number of resulting assets does not exceed the page size" }, "206" : { "content" : { "application/x.topdesk-am-assets-v1+json;qs=0.5" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } }, "application/x.topdesk-am-assets-v2+json" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } } }, "description" : "When the query is successful and the number of resulting assets is above the page size" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Returns assets which meet the given criteria.", "tags" : [ "Assets" ] }, "post" : { "description" : "Creates a new asset. To create a new asset, you will need the type of the asset you want to create (type_id), and to fill in the values of the mandatory fields of that specific asset type/template. You can get the ID of the available types of assets/templates using the /assetmgmt/templates endpoint. In order to get the fields of an asset, you can use the /assetmgmt/assets/blank endpoint.", "operationId" : "createAsset", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExampleCreateModel" } } }, "description" : "This object contains key-value pairs, where the key is the field's ID, and the value is the value of this field. This model must contain every mandatory field with a value." }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "successful operation" }, "202" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "The asset has been created successfully but at least one field in the request body is unknown and is therefore ignored. This can be the case for example when the field is removed from the template of the new asset concurrently." }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ValidationErrorsResponse" } } }, "description" : "On validation errors" }, "403" : { "description" : "When user doesn't have 'create' permission for the asset type." } }, "summary" : "Creates a new asset.", "tags" : [ "Assets" ] } }, "/assets/assignments" : { "put" : { "description" : "Assigns assets, stocks and bulk items with proper type of cards.\n
  • Assets can be assigned to locations, branches, persons and person groups
  • Stocks can be assigned to a single branch or location
  • Bulk items can be assigned to a branches or locations
\n\nBulk linking of multiple assets, stocks and bulk items to a single card is supported within one request.\nThe maximum number of assets/stocks/bulk items to be handled within a single request is 50.\n\nThe type of the assignment (linkType) and the ID of the card to be assigned is required to assign a card to the asset, stock or bulk item.\n", "operationId" : "assign", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkAssignmentRequest" } } }, "description" : "assetIds is an asset, stock or bulk item ID array. Multiple values of the array is supported\n\nlinkType is the type of the target card - branch, location for assets, stocks and bulk items while person, personGroup is only for assets\n\nlinkToId is the ID of the target card\n\nbranchId (optional) - is the parent branch ID of the location.", "required" : true }, "responses" : { "200" : { "content" : { "application/x.topdesk-am-assignment-links-v1+json" : { "schema" : { "$ref" : "#/components/schemas/AssignmentLinkResponse" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • Assigning person or person group to stocks or bulk items is not allowed.
  • Asset ID array has constraints: there aren't any asset IDs defined or the size of the asset IDs array exceeds the limit of 50 items.
  • There is an asset ID duplication.
  • One of the assets, stocks or bulk items is archived or not found.
  • Location, branch, person or person group to be assigned is not found.
  • When the assignment is archived.
" }, "403" : { "description" : "Possible causes:
  • When the user doesn't have permission for the operation.
" }, "409" : { "description" : "One of the assets, stocks or bulk items is already assigned with the target card." } }, "summary" : "Add branch, location, person and person group assignments to assets, stocks or bulk items.", "tags" : [ "Assignments" ] } }, "/assets/blank" : { "get" : { "description" : "Returns a blank asset card based on a specific template. The template is identified by the value of the templateId or the templateName parameter. Identification based on the templateName parameter is supported only when the template has a custom, user-specified name. In other words, default, translated template names cannot be matched with it.The result includes all the fields on the card, and their properties. You can use this endpoint to see the mandatory fields of the asset, and with that, create new assets of that type.", "operationId" : "getBlankAsset", "parameters" : [ { "description" : "ID of the template", "in" : "query", "name" : "templateId", "schema" : { "type" : "string" } }, { "description" : "Name of the template", "in" : "query", "name" : "templateName", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful query" }, "400" : { "description" : "When both templateId and templateName are given but they point to different templates, or when neither of them is given." }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." }, "404" : { "description" : "When templateId or templateName does not match the unique ID or the name of any template, respectively." } }, "summary" : "Retrieves a blank, not-yet-persisted asset based on the given templateId or templateName.", "tags" : [ "Assets" ] } }, "/assets/delete" : { "post" : { "description" : "Deletes the given assets.It may be possible that one or more assets couldn't be deleted because they have existing links from other components. In this case those assets' IDs will be listed in the 'failed' list of the response, but it doesn't affect deletion of other assets.", "operationId" : "deleteAssets", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssetListOperationRequest" } } }, "description" : "Ids of assets to be deleted." }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DeleteAssetsResponse" } } }, "description" : "When operation was executed successfully. (This might also include some assets which couldn't be deleted.)" } }, "summary" : "Deletes several assets", "tags" : [ "Assets" ] } }, "/assets/deleteGridFieldAsset" : { "post" : { "description" : "This operation changes the etag-value of the host asset which contains the dataset.The new etag is sent back in the response as the `etag` property. In subsequent calls the newly received etag should be used.\n\n⚠️ If the asset card, which was modified by this API call, is open in a browser, that view should be refreshed because by changing the dataset the displayed card becomes outdated and further modifications won't succeed.", "operationId" : "deleteGridFieldAsset", "parameters" : [ { "description" : "id of the row to be deleted.", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "id of the host asset.", "in" : "query", "name" : "hostAssetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExampleDeleteModel" } } }, "description" : "This object contains key-value pairs, where the key is the ID of the field, and the value is its new value. All properties in this model are mandatory.", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DeleteGridAssetResponse" } } }, "description" : "On successful deletion" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ValidationErrorsResponse" } } }, "description" : "On validation errors" }, "403" : { "description" : "When user doesn't have 'write' permission for the required asset type." }, "404" : { "description" : "When the asset with the provided ID isn't found" }, "409" : { "description" : "On concurrent modification (when ETags don't match)" } }, "summary" : "Deletes a row from the grid widget and updates host asset.", "tags" : [ "Assets" ] } }, "/assets/filter" : { "post" : { "description" : "The functionality of this endpoint is identical with that of the `GET /assets` endpoint, except that query parameters are expected to be provided as properties in the request body. This solution makes it possible to construct longer parameter lists and thus more complex filtering, which would not work with `GET /assets` due to the limited length of URLs.\n\nThe request body is a JSON object where each property represents a parameter which would be a query parameter otherwise. When there are multiple query parameters with the same name, they can be represented by a JSON-array value.\n\nExample:\n\n```\n{\n \"templateId\": [\n \"5f8f1285-c4de-4d3f-b7b5-31063509fa24\",\n \"608a1fa9-91e0-423a-9c0b-ad32fe6961e9\"\n ],\n \"$filter\": \"somefield eq 'somevalue'\"\n}\n```\n\nFor possible parameters and responses check the documentation of the `GET /assets` endpoint.", "operationId" : "getAssetsAdvanced", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "additionalProperties" : { "type" : "object" } } } } }, "responses" : { "default" : { "content" : { "application/x.topdesk-am-assets-v1+json;qs=0.5" : { }, "application/x.topdesk-am-assets-v2+json" : { } }, "description" : "default response" } }, "summary" : "Returns assets which meet the given criteria. Identical with `GET /assets` but can handle a longer parameter list.", "tags" : [ "Assets" ] } }, "/assets/getGridFieldValues" : { "get" : { "description" : "⚠️**Deprecation warning**: the `application/x.topdesk-am-assets-v1+json` media type is deprecated and is going to be removed in a future release. We strongly recommend setting the Accept header of each request to `application/x.topdesk-am-assets-v2+json` in order to get the new version of the assets resource and to follow the best practice of depending on a specific resource version explicitly.\n\nTimeline:\n- After the end of April, 2024, support for the `application/x.topdesk-am-assets-v1+json` media type is going to be dropped entirely.", "operationId" : "getGridFieldValues", "parameters" : [ { "description" : "ID of the host asset", "example" : "aa6712d9-da6a-4393-bf12-6002b8b1c1fc", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "ID of the grid field for which values are requested", "example" : "@gridwidgetfield_0997a0f7-a20c-4d5a-a28f-14bafe2c1593", "in" : "query", "name" : "fieldId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-assets-v1+json;qs=0.5" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } }, "application/x.topdesk-am-assets-v2+json" : { "schema" : { "$ref" : "#/components/schemas/GridAssetStructureResponse" } } }, "description" : "On successful query" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Gets assets of grid field.", "tags" : [ "Assets" ] } }, "/assets/gridFieldAsset" : { "get" : { "operationId" : "getGridFieldAssetById", "parameters" : [ { "description" : "id of the requested asset (row in grid field).", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "id of the host asset.", "in" : "query", "name" : "hostAssetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful query" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Retrieves a line of the grid field based on the assetId (of the line) and the hostAssetId (which is the asset the grid field belongs to).", "tags" : [ "Assets" ] }, "post" : { "operationId" : "updateGridFieldAsset", "parameters" : [ { "description" : "The ID of the row to be edited.", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the host asset.", "in" : "query", "name" : "hostAssetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExampleSaveModel" } } }, "description" : "This object contains key-value pairs, where the key is the ID of the modified field, and the value is its new value. If a mandatory field is not given in this model, then its value remains the same.", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful update" }, "202" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "The row has been updated successfully but at least one field in the request body is unknown and is therefore ignored. This can be the case for example when the field is removed from the template of the host asset concurrently." }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ValidationErrorsResponse" } } }, "description" : "On validation errors" }, "403" : { "description" : "When user doesn't have 'write' permission for the required asset type." }, "404" : { "description" : "When the host asset or the row with the provided ID isn't found. This includes the case when the row does not belong to the specified host asset." }, "409" : { "description" : "On concurrent modification (when ETags don't match)" } }, "summary" : "Updates an existing row.", "tags" : [ "Assets" ] } }, "/assets/linkedKnowledgeItem" : { "post" : { "description" : "Maximum number of assets is 50.", "operationId" : "linkKnowledgeItemToAssets", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OneKnowledgeItemToManyAssetsRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkLinkResponse" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • Asset is not found.
  • Asset is archived.
  • Maximum number of assets exceeded.
  • Mandatory fields are missing.
  • Knowledge item is not found.
" }, "403" : { "description" : "No 'write' permission for the knowledge item or 'read' permission for any of the assets." }, "409" : { "description" : "The link already exists." } }, "summary" : "Add links between a knowledge item and one or more assets. Linking archived knowledge item is supported.", "tags" : [ "Knowledge Items" ] } }, "/assets/linkedService" : { "post" : { "description" : "Maximum number of assets is 50.", "operationId" : "linkServiceToAssets", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OneServiceToManyAssetsRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkLinkResponse" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • Asset is not found.
  • Asset is archived.
  • Maximum number of assets exceeded.
  • Mandatory fields are missing.
  • Service or supplier service is not found.
  • The service or supplier service is archived.
" }, "403" : { "description" : "Possible causes:
  • No 'write' permission for the service or supplier service or 'read' permission for any of the assets.
" }, "409" : { "description" : "The link already exists." } }, "summary" : "Add links between a service, supplier service and one or more assets.", "tags" : [ "Services" ] } }, "/assets/linkedTask" : { "post" : { "description" : "Maximum number of assets is 50.", "operationId" : "linkTaskToAssets", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/OneTaskToManyAssetsRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkLinkResponse" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • Asset is not found.
  • Asset is archived.
  • Maximum number of assets exceeded.
  • Mandatory fields are missing.
  • Task with type is not found.
  • The task is archived.
" }, "403" : { "description" : "Possible causes:
  • No 'write' permission for the task or 'read' permission for any of the assets.
" }, "409" : { "description" : "The link already exists." } }, "summary" : "Add links between a change, change activity, incident, operational activity, operational series, problem and one or more assets.", "tags" : [ "Tasks" ] } }, "/assets/templateId/{templateId}" : { "get" : { "description" : "Returns a list of all assets of a given type. By default, only active assets are returned, and per asset, only the ID of each asset is included. This is customizable through query parameters.

\n| Permission | Remarks |\n| --- | --- |\n| Operator | With read permission for the given asset type |\n| Person | No access |", "operationId" : "getAssetsByTemplateId", "parameters" : [ { "description" : "The template ID specifying the type of assets to return.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "Which asset fields to include in the response. If not specified, only the ID will be included. Fields should be referenced by their field ID, not their display name.", "example" : "name", "in" : "query", "name" : "field", "schema" : { "type" : "array", "items" : { "type" : "string" } } }, { "description" : "Whether to include archived assets in the response. By default, only active assets are returned.", "example" : true, "in" : "query", "name" : "includeArchived", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssetResults" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • The 'field' query parameter is used with a value that is not an ID of a field on the asset template.
" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
" } }, "summary" : "Returns a list of all assets of a given type.", "tags" : [ "Asset Management Import API" ] }, "post" : { "description" : "Creates a new asset. The request body should contain a key:value mapping from field IDs to desired values. You can use the cardTypes operation to retrieve the available fields on a template (including their ID and type). The following rules apply:
  • Values must be in the correct format for that field's type:
    • BOOLEAN: A json boolean.
    • NUMBER: A json number.
    • STRING: A json string.
    • DATE: A json string in ISO 8601 format.
    • FOREIGN_KEY: A json string in uuid format.
    • FOREIGN_KEY_LIST: A json array of json strings in uuid format.
  • All fields which are set to 'required' on this asset type must be filled in.
  • Even for asset types where the 'name' field is not required, it can not be 'null' or an empty string. It must either be a non-empty json string or omitted completely. If it is omitted, the new asset will receive a name according to the automatic numbering configured for the asset type.
  • If the name of the asset is provided, it must be unique among _all_ assets (including assets of different types).


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With create permission for the specified asset type |\n| Person | No access |", "operationId" : "createByImport", "parameters" : [ { "description" : "The template ID specifying which type of asset to create.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "additionalProperties" : { "type" : "object" } } } }, "description" : "A flat json object representing the asset to be created. The keys are field IDs and the values are the asset's values for those fields.", "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreatedAsset" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • Some key in the request body is not an ID of a field on the asset template.
  • Some value in the request body does not have the correct format for that field's type.
  • A mandatory field is not filled in.
  • The name of the asset is not unique.
" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
" } }, "summary" : "Creates a new asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}" : { "patch" : { "description" : "Updates an existing asset. The request body should contain a key:value mapping from field IDs to desired values. You can use the cardTypes operation to retrieve the available fields on a template (including their ID and type). The following rules apply:
  • Values must be in the correct format for that field's type:
    • BOOLEAN: A json boolean.
    • NUMBER: A json number.
    • STRING: A json string.
    • DATE: A json string in ISO 8601 format.
    • FOREIGN_KEY: A json string in uuid format.
    • FOREIGN_KEY_LIST: A json array of json strings in uuid format.
  • Only the specified fields will be updated, all others remain unchanged.
  • To clear a value, set the field to null. Required fields cannot be cleared.
  • The name of each asset must remain unique among _all_ assets (including assets of different types).
  • If the asset to be updated is archived, it will be unarchived as a result of this operation.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for assets, and permission to (un)archive assets if the specified asset is archived |\n| Person | No access |", "operationId" : "modifyByImport", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to be updated.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "additionalProperties" : { "type" : "object" } } } }, "description" : "A flat json object representing the asset to be updated. The keys are field IDs and the values are the asset's values for those fields.", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ModifiedAssetResponse" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • Some key in the request body is not an ID of a field on the asset template.
  • Some value in the request body does not have the correct format for that field's type.
  • A mandatory field is cleared.
  • The name of the asset is not unique.
" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset does not exist.
" } }, "summary" : "Updates an existing asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}/archive" : { "post" : { "description" : "Archives an asset. The specified reason for archiving will be filled in. If the specified asset is already archived, nothing will happen (the reason for archiving will not be updated either).

\n| Permission | Remarks |\n| --- | --- |\n| Operator | With permission to (un)archive assets |\n| Person | No access |", "operationId" : "archiveAssetByTemplateAndAssetId", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to be archived.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ReasonForArchiving" } } }, "required" : true }, "responses" : { "204" : { "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • No reason for archiving is given.
" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset does not exist.
" } }, "summary" : "Archives an asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}/assignment/branches" : { "put" : { "description" : "Assigns branches to an asset. The request body contains a list of IDs of branches that should be assigned to the asset. The following rules apply:
  • This operation is only available for active assets with an assignment widget.
  • The specified list of branches represents the desired state of branch assignments. Branches in the list that were not yet assigned to the asset, will be assigned. Branches that were assigned to the asset but do not appear in the list, will be unassigned.
  • If any errors occur while (un)assigning branches, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "updateBranchLinks", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to assign the branches to.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset template does not contain an assignment widget.
  • The specified asset does not exist.
  • The specified asset is archived.
" } }, "summary" : "Assigns branches to an asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}/assignment/locations" : { "put" : { "description" : "Assigns locations to an asset. The request body contains a list of IDs of locations that should be assigned to the asset. The following rules apply:
  • This operation is only available for active assets with an assignment widget.
  • The specified list of locations represents the desired state of location assignments. Locations in the list that were not yet assigned to the asset, will be assigned. Locations that were assigned to the asset but do not appear in the list, will be unassigned.
  • If any errors occur while (un)assigning locations, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "updateLocationLinks", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to assign the locations to.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset template does not contain an assignment widget.
  • The specified asset does not exist.
  • The specified asset is archived.
" } }, "summary" : "Assigns locations to an asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}/assignment/personGroups" : { "put" : { "description" : "Assigns person groups to an asset. The request body contains a list of IDs of person groups that should be assigned to the asset. The following rules apply:
  • This operation is only available for active assets with an assignment widget.
  • The specified list of person groups represents the desired state of person group assignments. Person groups in the list that were not yet assigned to the asset, will be assigned. Person groups that were assigned to the asset but do not appear in the list, will be unassigned.
  • If any errors occur while (un)assigning person groups, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "updatePersonGroupLinks", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to assign the person groups to.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset template does not contain an assignment widget.
  • The specified asset does not exist.
  • The specified asset is archived.
" } }, "summary" : "Assigns person groups to an asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/templateId/{templateId}/{assetId}/assignment/persons" : { "put" : { "description" : "Assigns persons to an asset. The request body contains a list of IDs of persons that should be assigned to the asset. The following rules apply:
  • This operation is only available for active assets with an assignment widget.
  • The specified list of persons represents the desired state of person assignments. Persons in the list that were not yet assigned to the asset, will be assigned. Persons that were assigned to the asset but do not appear in the list, will be unassigned.
  • If any errors occur while (un)assigning persons, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "updatePersonLinks", "parameters" : [ { "description" : "The template ID specifying the type of the asset.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb", "in" : "path", "name" : "templateId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the asset to assign the persons to.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset template does not exist.
  • The specified asset template is archived.
  • The specified asset template does not contain an assignment widget.
  • The specified asset does not exist.
  • The specified asset is archived.
" } }, "summary" : "Assigns persons to an asset.", "tags" : [ "Asset Management Import API" ] } }, "/assets/unlink/{type}/{targetId}" : { "post" : { "operationId" : "removeMultipleAssignments", "parameters" : [ { "description" : "Type of the linked entity.", "in" : "path", "name" : "type", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Id of the linked entity.", "in" : "path", "name" : "targetId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UnlinkParameters" } } }, "description" : "This object should contain a list of assetIds to be unlinked." }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UnlinkResponse" } } }, "description" : "Deleting is successful" }, "403" : { "description" : "No 'write' permission for the target entity or 'read' permission for any of the assets." } }, "summary" : "Delete links between the specified entity and one or more assets.", "tags" : [ "Assignments" ] } }, "/assets/{assetId}" : { "get" : { "operationId" : "getAssetById", "parameters" : [ { "description" : "id of the requested asset.", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "pattern" : "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" } }, { "description" : "When set to true, functionalities available for the asset are included in the response.", "in" : "query", "name" : "includeFunctionalities", "schema" : { "type" : "string", "default" : "true" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful query" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." } }, "summary" : "Retrieves an asset based on the given assetId.", "tags" : [ "Assets" ] }, "post" : { "operationId" : "updateAssetById", "parameters" : [ { "description" : "id of the asset to update", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid", "pattern" : "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExampleSaveModel" } } }, "description" : "This object contains key-value pairs, where the key is the modified field's ID, and the value is the new value. If a mandatory field is not given in this model, then it's value remains the same.", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful update" }, "202" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "The asset has been updated successfully but at least one field in the request body is unknown and is therefore ignored. This can be the case for example when the field is removed from the template of the asset concurrently." }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ValidationErrorsResponse" } } }, "description" : "On validation errors" }, "403" : { "description" : "When user doesn't have 'write' permission for the required asset type." }, "404" : { "description" : "When the asset with the provided ID isn't found" }, "409" : { "description" : "On concurrent modification (when ETags don't match)" } }, "summary" : "Updates an existing asset.", "tags" : [ "Assets" ] } }, "/assets/{assetId}/actions" : { "get" : { "operationId" : "getActions", "parameters" : [ { "description" : "The ID of the asset", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ManualTriggersResponse" } } }, "description" : "successful operation" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." }, "404" : { "description" : "When asset is not found" } }, "summary" : "Get available actions for the asset.", "tags" : [ "Actions" ] } }, "/assets/{assetId}/archive" : { "post" : { "description" : "Archives the asset identified by the provided ID (assetId). To archive an asset you need to provide a reason for archiving (reasonId) in the body. The endpoint for retrieving the available reasons can be found in the General API.", "operationId" : "archiveAsset", "parameters" : [ { "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Reason" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful archive" }, "403" : { "description" : "When user doesn't have 'archive' permission for the asset type." } }, "summary" : "Archives an asset.", "tags" : [ "Assets" ] } }, "/assets/{assetId}/assignments" : { "get" : { "description" : "Returns a list of assigned locations, branches, persons and person groups of a specific asset. Branch filters are applied.", "operationId" : "getAssignments", "parameters" : [ { "description" : "The ID of the asset", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "Include inherited assignments in the response. Inherited assignments do not have a linkId, but have an inheritanceParentId (the id of the asset it is inherited from).", "in" : "query", "name" : "includeInherited", "schema" : { "type" : "boolean", "default" : false } }, { "description" : "The maximum number of assignments to return in one response. Must be a decimal number greater than 0.", "example" : 42, "in" : "query", "name" : "limit", "schema" : { "type" : "string", "minimum" : 1 } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-assignments-v1+json" : { "schema" : { "$ref" : "#/components/schemas/Links" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • `limit` is too small
  • `limit` is not a number
" }, "403" : { "description" : "When user doesn't have 'read' permission for the asset type." }, "404" : { "description" : "When asset is not found" } }, "summary" : "Get assignments for asset.", "tags" : [ "Assignments" ] }, "put" : { "description" : "Assigns the asset/stock/bulk item to the target card.\n\n
  • Assets can be assigned to locations, branches, persons and person groups
  • Stocks can be assigned to a single branch or location
  • Bulk items can be assigned to branches or locations
\n\nThe type of the assignment (linkType) and the ID of the card to be assigned is required to assign a card to the asset, stock or bulk item.", "operationId" : "assignById", "parameters" : [ { "description" : "ID of asset, stock or bulk item which is the subject of the assignment", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssignmentRequest" } } }, "description" : "linkType is the type of the target card - branch, location for assets, stocks and bulk items while person, personGroup is only for assets\n\nlinkToId is the ID of the target card\n\nbranchId (optional) - is the parent branch ID of the location.", "required" : true }, "responses" : { "200" : { "content" : { "application/x.topdesk-am-assignment-links-v1+json" : { "schema" : { "$ref" : "#/components/schemas/AssignmentLinkResponse" } } }, "description" : "successful operation" }, "400" : { "description" : "Possible causes:
  • Assigning person or person group to a stock or bulk item is not allowed.
  • Asset, stock or bulk item is archived or not found
  • Invalid link type or link type does not match with the linkToId
  • Location, branch, person or person group to be assigned not found
  • When the assignment is archived.
" }, "403" : { "description" : "Possible causes:
  • When the user doesn't have permission for the operation.
" }, "409" : { "description" : "The asset, stock or bulk item is already assigned with the target card." } }, "summary" : "Add branch, location, person and person group assignment to a single asset, stock or bulk item.", "tags" : [ "Assignments" ] } }, "/assets/{assetId}/assignments/{linkId}" : { "delete" : { "description" : "Removes an assigned branch, location, person, or person group from an asset. To unassign something, you need to provide the linkId, which you can retrieve with the GET /assets/{assetId}/assignments endpoint.", "operationId" : "unassign", "parameters" : [ { "description" : "The ID of the asset", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the assignment", "in" : "path", "name" : "linkId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "description" : "Deleting is successful" }, "403" : { "description" : "When user doesn't have 'write' permission for the card type they want to unassign the asset from." }, "404" : { "description" : "When either the asset or the assignment is not found" } }, "summary" : "Removes an assigned branch, location, person, or person group", "tags" : [ "Assignments" ] } }, "/assets/{assetId}/copy" : { "post" : { "description" : "It is only available for active assets. The mandatory fields are dependent on the auto numbering settings of the source asset's template. If it is enabled only the numberOfCopies should be provided. Otherwise prefix and start at are also mandatory.", "operationId" : "copyAsset", "parameters" : [ { "description" : "id of the asset to copy", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ExampleCopyModel" } } }, "description" : "This object contains key-value pairs which are used to define the amount and the asset id of the copies", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CopyAssetResponseList" } } }, "description" : "successful operation" }, "400" : { "description" : "When an asset id which should be created during the copy is already taken. Or when the auto numbering settings are in conflict with the provided prefix and/or start at values. (When auto numbering is set but prefix and/or start at are provided, or when auto numbering is not set and prefix or start at are missing." }, "403" : { "description" : "When the user does not have 'create' permission for assets or does not have 'read' permission for all the linked assets of the source asset." }, "404" : { "description" : "When the provided asset id does not belong to any existing asset." } }, "summary" : "Copies an asset.", "tags" : [ "Assets" ] } }, "/assets/{assetId}/history/currentItems" : { "get" : { "description" : "Read permission is required for the particular asset.", "operationId" : "getCurrentItems", "parameters" : [ { "description" : "Id of the asset.", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "It's possible to filter for different categories of items. This parameter can contain a comma-separated list of event filter IDs which should be excluded from the result. If it's not given, all items are returned. Possible values (with the resource categories for which they are applicable in parentheses, where 'all' means every resource category):
  • asset_management_assignment_modifications (all)
  • asset_management_document_modifications (asset)
  • asset_management_modifications (all)
  • asset_management_relationship_modifications (all)
  • asset_management_reservation_setting_modifications (asset)
  • asset_management_status (asset)
  • change_management_filter (asset)
  • incident_management_filter (asset)
  • knowledge_item_filter (asset)
  • long_term_maintenance_filter (asset)
  • operations_management_filter (asset)
  • problem_management_filter (asset)
  • asset_management_stock_quantity_changes (stock, bulkItem)
", "in" : "query", "name" : "excludedCategories", "schema" : { "type" : "string" } }, { "description" : "Used for paging. It contains a surrogate key which is derived from an event. (date / type / id) If this is given, only those events will be returned which have alphabetically smaller key than the given parameter. This mechanism supports paging for multiple events in the same millisecond.", "in" : "query", "name" : "lastSeen", "schema" : { "type" : "string" } }, { "description" : "Controls how many elements the result should have.If there are more results than the page size, a 'next' property will contain a URI for the next page in the result.Max value is 1000. Default: 10.", "in" : "query", "name" : "pageSize", "schema" : { "type" : "integer", "format" : "int32", "default" : 10 } }, { "description" : " If it's set to true, the response will contain further data(formatting info, translation info, meta-data) which is used internally by the standard frontend and it's subject to breaking changes.", "in" : "query", "name" : "includeAuxiliaryInfo", "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HistoryItemCollection" } } }, "description" : "On successful query." }, "403" : { "description" : "When user doesn't have read permission for this asset." } }, "summary" : "Returns list of external links to the specified asset as items.", "tags" : [ "Assets" ] } }, "/assets/{assetId}/history/pastItems" : { "get" : { "description" : "Read permission is required for the particular asset.", "operationId" : "getPastItems", "parameters" : [ { "description" : "Id of the asset.", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "It's possible to filter for different categories of items. This parameter can contain a comma-separated list of event filter IDs which should be excluded from the result. If it's not given, all items are returned. Possible values (with the resource categories for which they are applicable in parentheses, where 'all' means every resource category):
  • asset_management_assignment_modifications (all)
  • asset_management_document_modifications (asset)
  • asset_management_modifications (all)
  • asset_management_relationship_modifications (all)
  • asset_management_reservation_setting_modifications (asset)
  • asset_management_status (asset)
  • change_management_filter (asset)
  • incident_management_filter (asset)
  • knowledge_item_filter (asset)
  • long_term_maintenance_filter (asset)
  • operations_management_filter (asset)
  • problem_management_filter (asset)
  • asset_management_stock_quantity_changes (stock, bulkItem)
", "in" : "query", "name" : "excludedCategories", "schema" : { "type" : "string" } }, { "description" : "Used for paging. It contains a surrogate key which is derived from an event. (date / type / id) If this is given, only those events will be returned which have alphabetically smaller key than the given parameter. This mechanism supports paging for multiple events in the same millisecond.", "in" : "query", "name" : "lastSeen", "schema" : { "type" : "string" } }, { "description" : "Controls how many elements the result should have.If there are more results than the page size, a 'next' property will contain a URI for the next page in the result.Max value is 1000. Default: 10.", "in" : "query", "name" : "pageSize", "schema" : { "type" : "integer", "format" : "int32", "default" : 10 } }, { "description" : " If it's set to true, the response will contain further data(formatting info, translation info, meta-data) which is used internally by the standard frontend and it's subject to breaking changes.", "in" : "query", "name" : "includeAuxiliaryInfo", "schema" : { "type" : "boolean", "default" : false } }, { "description" : "Whether to include items from external sources. When an asset appears on a module card (first line incident, change request, etc) in the object / location block, usually it's considered to be an external event from Asset Management's perspective. Note, that Asset Management can't guarantee immutability and integrity of external events.", "in" : "query", "name" : "includeExternalItems", "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/HistoryItemCollection" } } }, "description" : "On successful query." }, "403" : { "description" : "When user doesn't have read permission for this asset." } }, "summary" : "Returns list of items from audit log and optionally from external sources which are related to the specified asset.", "tags" : [ "Assets" ] } }, "/assets/{assetId}/unarchive" : { "post" : { "operationId" : "unarchiveAsset", "parameters" : [ { "description" : "id of the asset to unarchive", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendAsset" } } }, "description" : "On successful unarchive" }, "403" : { "description" : "When user doesn't have 'archive' permission for the asset type." } }, "summary" : "Unarchives an asset.", "tags" : [ "Assets" ] } }, "/capabilities" : { "get" : { "operationId" : "get", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityListResponse" } } }, "description" : "On successful query." }, "403" : { "description" : "When user doesn't have any permission for the module." } }, "summary" : "Returns list of all link types.", "tags" : [ "Link Types" ] }, "post" : { "operationId" : "createCapability", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityCreateRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityDto" } } }, "description" : "On successful creation" }, "400" : { "description" : "If name is empty, too long or another link type has this name already." }, "403" : { "description" : "When user doesn't have 'write' permission for templates." } }, "summary" : "Creates a new link type.", "tags" : [ "Link Types" ] } }, "/capabilities/{capabilityId}" : { "delete" : { "operationId" : "deleteCapability", "parameters" : [ { "in" : "header", "name" : "If-Match", "schema" : { "type" : "string" } }, { "description" : "Id of the link type", "in" : "path", "name" : "capabilityId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "204" : { "description" : "On successful deletion" }, "400" : { "description" : "If link type is used in any relation or it is a built in link type." }, "403" : { "description" : "When the user lacks either 'write' or 'delete' permissions for templates." }, "404" : { "description" : "When link type doesn't exist." }, "412" : { "description" : "On concurrent modification (when ETags don't match)" } }, "summary" : "Deletes a link type.", "tags" : [ "Link Types" ] }, "get" : { "operationId" : "getCapability", "parameters" : [ { "description" : "Id of the link type", "in" : "path", "name" : "capabilityId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "Include if there is a relation between assets with the specified capability", "in" : "query", "name" : "includeUsage", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/FrontendCapability" } } }, "description" : "On successful query" }, "404" : { "description" : "When the capability is not found." } }, "summary" : "Returns the link type with the ID specified in the path.", "tags" : [ "Link Types" ] }, "post" : { "operationId" : "updateCapability", "parameters" : [ { "description" : "Id of the link type", "in" : "path", "name" : "capabilityId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityEditRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityDto" } } }, "description" : "On successful update" }, "400" : { "description" : "If new name is empty, too long or another link type has this name already." }, "403" : { "description" : "When user doesn't have 'write' permission for templates." }, "409" : { "description" : "Concurrent modification" } }, "summary" : "Updates the name or inheritance status of an existing link type", "tags" : [ "Link Types" ] } }, "/capabilities/{capabilityId}/archive" : { "post" : { "description" : "Archives the link type identified by the provided ID (capabilityId).", "operationId" : "archiveCapability", "parameters" : [ { "description" : "Id of the link type", "in" : "path", "name" : "capabilityId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityDto" } } }, "description" : "On successful archive" }, "400" : { "description" : "If link type is already archived." }, "403" : { "description" : "When user doesn't have 'archive' permission for templates." } }, "summary" : "Archives a link type.", "tags" : [ "Link Types" ] } }, "/capabilities/{capabilityId}/unarchive" : { "post" : { "operationId" : "unarchiveCapability", "parameters" : [ { "description" : "Id of the link type", "in" : "path", "name" : "capabilityId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CapabilityDto" } } }, "description" : "On successful unarchive" }, "400" : { "description" : "If link type isn't archived." }, "403" : { "description" : "When user doesn't have 'archive' permission for templates." } }, "summary" : "Unarchives a link type.", "tags" : [ "Link Types" ] } }, "/cardTypes" : { "get" : { "description" : "Returns a list of all active asset templates. Information about each template includes:
  • The name and ID of the template
  • Details of the fields that are present on the template
  • The API operations available for the template


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With read permission for any asset type |\n| Person | No access |", "operationId" : "getCardTypeTemplates", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CardTypes" } } }, "description" : "successful operation" } }, "summary" : "Returns a list of all asset templates.", "tags" : [ "Asset Management Import API" ] } }, "/dropdowns/{dropdownId}" : { "get" : { "description" : "Returns a list of all options for a given dropdown that has its own options defined in Asset Management. By default, only the ID of each option is included. To also include the name, use `field=name` as a query parameter in the URL.

\n| Permission | Remarks |\n| --- | --- |\n| Operator | Unrestricted access |\n| Person | No access |", "operationId" : "getDropdownValues", "parameters" : [ { "description" : "The template ID or field key of the dropdown whose options to return.", "example" : "78a17c25-1ae0-4a2b-a341-1330ac53ae69 or my-dropdown", "in" : "path", "name" : "dropdownId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Use this query parameter to also include the names of the dropdown options in the response. If not specified, only the ID will be returned.", "example" : "name", "in" : "query", "name" : "field", "schema" : { "type" : "array", "enum" : [ "name" ], "items" : { "type" : "string", "enum" : [ "name" ] } } }, { "description" : "Whether to include archived dropdown options in the response. By default, only active dropdown options are returned.", "example" : true, "in" : "query", "name" : "includeArchived", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DropdownOptionResults" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • The 'field' query parameter is used with a different value than 'name'.
" }, "404" : { "description" : "Possible causes:
  • The specified dropdown does not exist.
  • The specified dropdown does not have its own options (i.e., selectable options come from another module).
" } }, "summary" : "Returns a list of all own options for a given dropdown.", "tags" : [ "Asset Management Import API" ] }, "post" : { "description" : "If an option with the given name (case-insensitive) already exists, the ID of that option is returned. If the existing option was archived, it will be unarchived. If no option with the given name exists, a new option is created, and the ID of the created option is returned.

\n| Permission | Remarks |\n| --- | --- |\n| Operator | With read permission on any asset type (if the checkbox 'Users can add options' is checked for the given dropdown) or write permission on asset templates (otherwise). |\n| Person | No access |", "operationId" : "getOrCreateDropdownValue", "parameters" : [ { "description" : "The field key of the dropdown for which to retrieve or create an option.", "example" : "my-dropdown", "in" : "path", "name" : "dropdownId", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DropdownOptionName" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DropdownOptionId" } } }, "description" : "An option with the given name already exists." }, "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DropdownOptionId" } } }, "description" : "A new option with the given name is created." }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • The given name is null, blank or too long (more than 60 characters).
" }, "404" : { "description" : "Possible causes:
  • The specified dropdown does not exist.
" } }, "summary" : "Retrieves or creates an option for a given dropdown.", "tags" : [ "Asset Management Import API" ] } }, "/fields" : { "get" : { "description" : "⚠️**Deprecation warning**: the `application/x.topdesk-am-fields-v1+json` media type is deprecated and is going to be removed in a future release. As a consequence, the response for all types of fields are changed. The new response structure can be browsed below in the `Responses` section by selecting the `application/x.topdesk-am-fields-v2+json` media type and choosing the `Schema` option. We strongly recommend setting the Accept header of each request to `application/x.topdesk-am-fields-v2+json` in order to get the new version of the field resource and to follow the best practice of depending on a specific resource version explicitly. For further information check the API release notes migration guide.\n\nTimeline:\n- Shortly after the 17th of October, 2025, the media type of the response is going to be changed from `application/x.topdesk-am-fields-v1+json` to `application/x.topdesk-am-fields-v2+json` when the Accept header of the request is set to `application/json` or when that header is not set. This does not affect clients that request one of the more specific media types explicitly.\n- After the 17th of December, 2025 support for the `application/x.topdesk-am-fields-v1+json` media type is going to be dropped entirely.", "operationId" : "getFields", "parameters" : [ { "description" : "Include fields only if their display name contains the given text fragment.", "in" : "query", "name" : "searchTerm", "schema" : { "type" : "string" } }, { "description" : "Fields that are available on templates of the specified category are considered to be used. All other fields are also included but marked as unused by setting their `archived` property to `true` or `inUse` property to `false` depending on the media type in Accept header:\n\n- `application/x.topdesk-am-fields-v1+json`: `archived`\n\n- `application/x.topdesk-am-fields-v2+json`: `inUse`.", "in" : "query", "name" : "resourceCategory", "schema" : { "type" : "string", "default" : "asset", "enum" : [ "asset", "stock", "bulkItem" ] } }, { "description" : "Include fields only from this set of templates.", "in" : "query", "name" : "templateId", "schema" : { "type" : "array", "items" : { "type" : "string", "format" : "uuid" }, "uniqueItems" : true } }, { "description" : "Exclude fields that are available only on this set of templates. If used together with the templateId parameter, the resulting fields are the ones that are available on the templates specified by the templateId parameter(s), minus the ones that are available only on the templates specified by the excludedTemplateId parameter(s).", "in" : "query", "name" : "excludedTemplateId", "schema" : { "type" : "array", "items" : { "type" : "string", "format" : "uuid" }, "uniqueItems" : true } }, { "description" : "Include fields only from templates for which asset read permission is granted. Consequently, fields from grid widget templates are excluded.", "in" : "query", "name" : "includeFromVisibleTemplatesOnly", "schema" : { "type" : "boolean", "default" : false } }, { "description" : "Include `inUse` property in the response. ⚠️ Applied only with `application/x.topdesk-am-fields-v2+json` media type in Accept header. If `resourceCategory` query parameter is specified, a field is considered to be in use only within the specified category.", "in" : "query", "name" : "includeInUse", "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-fields-v1+json" : { "schema" : { "$ref" : "#/components/schemas/FieldDefinitionListResponse" } }, "application/x.topdesk-am-fields-v2+json" : { "schema" : { "$ref" : "#/components/schemas/FieldListResponse" } } }, "description" : "successful operation" }, "403" : { "description" : "When user doesn't have any permission for the module." } }, "summary" : "Returns all fields.", "tags" : [ "Fields" ] } }, "/fields/{fieldId}" : { "delete" : { "description" : "Deletes a field permanently. It'll also delete all data recorded in the field. The field will be removed from templates, summary fields that use it, data set widgets, and saved overview filters.", "operationId" : "deleteField", "parameters" : [ { "description" : "Id of the field", "in" : "path", "name" : "fieldId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Deleting is successful" }, "403" : { "description" : "When user doesn't have 'delete' permission for templates." }, "404" : { "description" : "When field is not found" } }, "summary" : "Deletes a field permanently.", "tags" : [ "Fields" ] }, "get" : { "description" : "⚠️**Deprecation warning**: the `application/x.topdesk-am-fields-v1+json` media type is deprecated and is going to be removed in a future release. As a consequence, the response for all types of fields are changed. The new response structure can be browsed below in the `Responses` section by selecting the `application/x.topdesk-am-fields-v2+json` media type and choosing the `Schema` option. We strongly recommend setting the Accept header of each request to `application/x.topdesk-am-fields-v2+json` in order to get the new version of the field resource and to follow the best practice of depending on a specific resource version explicitly. For further information check the API release notes migration guide.\n\nTimeline:\n- Shortly after the 17th of October, 2025, the media type of the response is going to be changed from `application/x.topdesk-am-fields-v1+json` to `application/x.topdesk-am-fields-v2+json` when the Accept header of the request is set to `application/json` or when that header is not set. This does not affect clients that request one of the more specific media types explicitly.\n- After the 17th of December, 2025 support for the `application/x.topdesk-am-fields-v1+json` media type is going to be dropped entirely.", "operationId" : "getFieldById", "parameters" : [ { "description" : "Id of the field", "in" : "path", "name" : "fieldId", "required" : true, "schema" : { "type" : "string" } }, { "description" : "If possible functionalities should be included into the response", "in" : "query", "name" : "includeFunctionalities", "schema" : { "type" : "boolean", "default" : false } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-fields-v1+json" : { "schema" : { "$ref" : "#/components/schemas/FrontendFieldDefinition" } }, "application/x.topdesk-am-fields-v2+json" : { "schema" : { "$ref" : "#/components/schemas/FieldResponse" } } }, "description" : "On successful access" }, "403" : { "description" : "When user doesn't have any permission for the module." }, "404" : { "description" : "When field is not found" } }, "summary" : "Returns the field's definition.", "tags" : [ "Fields" ] } }, "/import/assets" : { "get" : { "description" : "Returns a list of all non-archived assets. By default, only the ID of each asset is included. This is customizable through query parameters. Only the 'name' field is currently supported. In order to retrieve other fields, use the API for querying the list of assets of a specific type instead.

\n| Permission | Remarks |\n| --- | --- |\n| Operator | With read permission for any asset type |\n| Person | No access |", "operationId" : "getAllAssets", "parameters" : [ { "description" : "Which asset fields to include in the response. If not specified, only the ID will be included. Only the 'name' and 'id' fields are currently supported.", "example" : "name", "in" : "query", "name" : "field", "schema" : { "type" : "array", "items" : { "type" : "string" } } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssetResults" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BadRequestEntity" } } }, "description" : "Possible causes:
  • The 'field' query parameter is used with a value that is not 'name' or 'id'.
" } }, "summary" : "Returns a list of all non-archived assets", "tags" : [ "Asset Management Import API" ] } }, "/import/assets/{assetId}/links/child" : { "put" : { "description" : "Sets the children of an asset. The request body contains a list of IDs of assets that should be children of the asset. The following rules apply:
  • This operation is only available for active assets with a relationships widget.
  • The specified list of assets represents the desired list of linked children. Assets in the list that were not yet linked to the asset as children, will be linked. Assets that were linked to the asset as children, but do not appear in the list, will be unlinked.
  • If the asset is itself already a direct or indirect child of one of the supplied assets, the linking with this specific asset will fail.
  • An asset cannot be linked to itself.
  • If any errors occur while (un)linking assets, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "replaceChild", "parameters" : [ { "description" : "The ID of the asset whose children to set.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset does not exist.
  • The specified asset is archived.
  • The asset template of the specified asset does not contain a relationships widget.
" } }, "summary" : "Sets the children of an asset.", "tags" : [ "Asset Management Import API" ] } }, "/import/assets/{assetId}/links/incoming/{linkTypeId}" : { "put" : { "description" : "Sets an asset's dependencies according to a specific link type. The request body contains a list of IDs of assets (or even of a single stock) that should be linked to the asset. The following rules apply:
  • This operation is only available for active assets.
  • An asset is required to have a template that has a relationships widget in order to be able to link it to another asset.
  • An asset is required to have a template that has a linked stock widget in order to be able to link it to a stock.
  • The specified list of assets represents the desired state of dependencies according to the specified link type. Assets in the list that were not yet linked to the asset as dependencies according to the specified link type, will be assigned. Assets that were linked to the asset as dependencies according to the specified link type, but do not appear in the list, will be unlinked. The same is true when the specified list contains the ID if a single stock, with one important difference: the link type can only be dad98dad-054b-41ae-a727-3e3b37342739 (\"asset is in stock\").
  • If one of the supplied assets has a template that does not provide the specified link type, the linking with this specific asset will fail.
  • An asset cannot be linked to itself.
  • If any errors occur while (un)linking assets, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "replaceIncoming", "parameters" : [ { "description" : "The ID of the asset whose dependencies to set.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the link type.", "example" : "e462d679-aec2-4cc8-b81d-09236de4c198", "in" : "path", "name" : "linkTypeId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset does not exist.
  • The specified asset is archived.
  • The asset template of the specified asset does not contain a relationships widget.
" } }, "summary" : "Sets an asset's dependencies according to a specific link type.", "tags" : [ "Asset Management Import API" ] } }, "/import/assets/{assetId}/links/outgoing/{linkTypeId}" : { "put" : { "description" : "Sets an asset's provided links according to a specific link type.The request body contains a list of IDs of assets that should be linked to the asset. The following rules apply:
  • This operation is only available for active assets with a relationships widget that provide the specified link type.
  • The specified list of assets represents the desired state of provided links according to the specified link type. Assets in the list that were not yet linked to the asset as provided links according to the specified link type, will be assigned. Assets that were linked to the asset as provided links according to the specified link type, but do not appear in the list, will be unlinked.
  • An asset cannot be linked to itself.
  • If any errors occur while (un)linking assets, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "replaceOutgoing", "parameters" : [ { "description" : "The ID of the asset whose provided links to set.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The ID of the link type.", "example" : "e462d679-aec2-4cc8-b81d-09236de4c198", "in" : "path", "name" : "linkTypeId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset does not exist.
  • The specified asset is archived.
  • The asset template of the specified asset does not contain a relationships widget, or does not provide the specified link type.
" } }, "summary" : "Sets an asset's provided links according to a specific link type.", "tags" : [ "Asset Management Import API" ] } }, "/import/assets/{assetId}/links/parent" : { "put" : { "description" : "Sets the parents of an asset. The request body contains a list of IDs of assets that should be parents of the asset. The following rules apply:
  • This operation is only available for active assets with a relationships widget.
  • The specified list of assets represents the desired list of linked parents. Assets in the list that were not yet linked to the asset as parents, will be linked. Assets that were linked to the asset as parents, but do not appear in the list, will be unlinked.
  • If the asset is itself already a direct or indirect parent of one of the supplied assets, the linking with this specific asset will fail.
  • An asset cannot be linked to itself.
  • If any errors occur while (un)linking assets, the response code will still be 200, and the errors will be listed in the response body.


\n| Permission | Remarks |\n| --- | --- |\n| Operator | With write permission for the asset type |\n| Person | No access |", "operationId" : "replaceParent", "parameters" : [ { "description" : "The ID of the asset whose parents to set.", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c", "in" : "path", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/IdList" } } } }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/LinkResults" } } }, "description" : "successful operation" }, "404" : { "description" : "Possible causes:
  • The specified asset does not exist.
  • The specified asset is archived.
  • The asset template of the specified asset does not contain a relationships widget.
" } }, "summary" : "Sets the parents of an asset.", "tags" : [ "Asset Management Import API" ] } }, "/stockQuantities" : { "get" : { "description" : "Queries all stocks linked to the bulk item specified using `bulkItemId` along with the quantity for each stock. When using `stockId`, the result of the query contains all bulk items linked to the specified stock along with the quantity for each bulk item.", "operationId" : "getAllStockQuantities", "parameters" : [ { "description" : "Identifies the stock for which quantities are to be queried. When set, the `bulkItemId` parameter must not be provided.", "example" : "f386943b-6039-4ecc-bc20-402b94bf7478", "in" : "query", "name" : "stockId", "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "Identifies the bulk item for which quantities are to be queried. When set, the `stockId` parameter must not be provided.", "example" : "e4a18843-0e30-4f06-afbc-deb22ee93059", "in" : "query", "name" : "bulkItemId", "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The maximum number of elements to return in one response. Must be between 0 and 1000, both inclusive.", "example" : 42, "in" : "query", "name" : "pageSize", "schema" : { "type" : "string", "default" : "100", "maximum" : 1000, "minimum" : 0 } }, { "description" : "The name of the last seen element. When set, the first element of the data set is a stock/bulk item, the name of which comes right after this one in the alphabetically ordered list of stocks/bulk items.", "example" : "IT Stock", "in" : "query", "name" : "lastSeenName", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/x.topdesk-am-stock-quantities-v0+json" : { "schema" : { "$ref" : "#/components/schemas/StockQuantitiesResponse" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponseEntity" } } }, "description" : "Possible causes:
  • Either `stockId` and `bulkItemId` are both set, or they are both missing
  • `pageSize` is out of bounds
  • `pageSize` is not a number
  • The specified `stockId` or `bulkItemId` does not exist
  • The client does not have permission to read the specified `stockId` or `bulkItemId`
" } }, "summary" : "Queries stock quantities for either a bulk item or a stock", "tags" : [ "Stock Quantities" ] }, "post" : { "description" : "Links a bulk item to a stock with the specified initial quantity.", "operationId" : "linkBulkItemToStock", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BulkItemInStockRequest" } } }, "description" : "Quantity and identifiers of the to be linked stock and bulk item.", "required" : true }, "responses" : { "201" : { "content" : { "application/x.topdesk-am-stock-quantity-v0+json" : { "schema" : { "$ref" : "#/components/schemas/StockQuantitiesItem" } } }, "description" : "successful operation" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponseEntity" } } }, "description" : "Possible causes:
  • The request body is missing
  • The request body does not contain all required properties
  • The request body contains invalid values, like a negative quantity or a stockId not formatted as a valid UUID
  • The specified stock or bulk item does not exist
  • The client does not have permission to read both the specified stock and bulk item
  • The client does not have permission to write the specified stock nor the bulk item
  • The specified stock is already linked to the bulk item
" } }, "summary" : "Links a bulk item to a stock", "tags" : [ "Stock Quantities" ] } }, "/stockQuantities/{id}" : { "delete" : { "operationId" : "unlinkBulkItemFromStock", "parameters" : [ { "description" : "Identifies the relationship for the stock and the bulk item.", "example" : "fae8bc90-411c-4b35-a0b3-45abac451915", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "204" : { "description" : "successful operation" }, "403" : { "description" : "The client does not have permission to write either the stock end or the bulk item end of the relationship." }, "404" : { "description" : "Possible causes:
  • The specified relationship does not exist
  • The client does not have permission to read both the stock and the bulk item end of the relationship.
" } }, "summary" : "Removes the link between a bulk item and a stock", "tags" : [ "Stock Quantities" ] }, "put" : { "description" : "Edits quantity of how much bulk item is available on a given stock.", "operationId" : "editStockQuantity", "parameters" : [ { "description" : "Identifies the relationship for the stock and the bulk item.", "example" : "fae8bc90-411c-4b35-a0b3-45abac451915", "in" : "path", "name" : "id", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } }, { "description" : "The If-Match header contains the ETag enclosed in double quotes.", "example" : "10fab27c", "in" : "header", "name" : "If-Match", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StockQuantityUpdatePayload" } } }, "description" : "The new value for quantity.", "required" : true }, "responses" : { "200" : { "content" : { "application/x.topdesk-am-stock-quantity-v0+json" : { "schema" : { "$ref" : "#/components/schemas/StockQuantitiesItem" } } }, "description" : "successful operation, quantity is updated" }, "400" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ErrorResponseEntity" } } }, "description" : "Possible causes:
  • The request body is missing
  • The request body does not contain all required properties
  • The request body contains invalid values, like a negative quantity
  • The If-Match header is an asterisk (*).
" }, "403" : { "description" : "The client does not have permission to write either the stock end or the bulk item end of the relationship." }, "404" : { "description" : "Possible causes:
  • The specified relationship does not exist
  • The client does not have permission to read both the stock and the bulk item end of the relationship.
" }, "412" : { "description" : "The If-Match header does not match the latest known ETag." }, "428" : { "description" : "The ETag is missing from the If-Match headers." } }, "summary" : "Edits bulk item quantity on a stock", "tags" : [ "Stock Quantities" ] } }, "/stockTotals" : { "get" : { "description" : "Returns which asset type is in how many stocks and how many instances of each particular asset type is in stock. Similarly, it also returns which bulk item is in how many stocks and what is the total quantity of each particular bulk item in stock.\n\n- Archived asset types, assets, and bulk items are always included in the list and in the counts.\n- Asset types for which the requester has no read permission are excluded from the statistics.\n- Bulk items that have a type for which the requester has no read permission are excluded from the statistics.\n- Resources (e.g. assets) which wouldn't be visible because of branch filters are excluded from the statistics.", "operationId" : "getStockTotals", "responses" : { "200" : { "content" : { "application/x.topdesk-am-link-statistics-v0+json" : { "schema" : { "$ref" : "#/components/schemas/LinkStatisticsResponse" } } }, "description" : "On successful query" } }, "summary" : "Returns information about what is in stock.", "tags" : [ "Stock Quantities" ] } }, "/templates" : { "get" : { "description" : "Returns the list of available templates/asset types with their IDs. You will need the ID when creating a new asset for that type or when filtering the list of assets on asset type.", "operationId" : "getAll", "parameters" : [ { "description" : "Whether to show archived templates. Leave out for all, or specify true/false for only archived, or only active templates, respectively.", "in" : "query", "name" : "archived", "schema" : { "type" : "boolean" } }, { "description" : "Whether to show templates for assets which the user doesn't have read permission for. If this parameter isn't specified the endpoint returns templates for assets which the user has read permission for.", "in" : "query", "name" : "includeNonReadable", "schema" : { "type" : "boolean" } }, { "description" : "The endpoint returns templates matching the specified category only.", "in" : "query", "name" : "resourceCategory", "schema" : { "type" : "string", "default" : "asset", "enum" : [ "asset", "stock", "bulkItem" ] } }, { "description" : "The endpoint returns those templates which contain the given searchTerm in their name. It's case insensitive.", "in" : "query", "name" : "searchTerm", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TemplateListResponse" } } }, "description" : "On success." }, "403" : { "description" : "When user doesn't have any kind of permission for the module." } }, "summary" : "Returns all templates.", "tags" : [ "Templates" ] } }, "/uploads" : { "get" : { "operationId" : "list", "parameters" : [ { "description" : "The ID of the asset, which contains the files", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UploadResponse" } } }, "description" : "successful operation" } }, "summary" : "Retrieves list of uploaded blobs of the given selector, e.g. asset.", "tags" : [ "Uploads" ] }, "post" : { "description" : "In the request body, one or more files can be uploaded, using multipart/form-data media type.", "operationId" : "upload", "parameters" : [ { "description" : "The ID of the asset, which contains the files", "in" : "query", "name" : "assetId", "required" : true, "schema" : { "type" : "string", "format" : "uuid" } } ], "requestBody" : { "content" : { "multipart/form-data" : { } }, "description" : "Files, that will be uploaded", "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UploadResponse" } } }, "description" : "All blobs uploaded." }, "400" : { "description" : "When the given Content-Transfer-Encoding is unsupported, or when the Content-Type header is not set." }, "403" : { "description" : "When user doesn't have 'write' permission for the asset type." } }, "summary" : "Uploads one or more blobs.", "tags" : [ "Uploads" ] } }, "/uploads/{uploadId}" : { "delete" : { "operationId" : "deleteUpload", "parameters" : [ { "description" : "The ID of the blob", "in" : "path", "name" : "uploadId", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "204" : { "description" : "Upon successful deletion" }, "403" : { "description" : "When user doesn't have 'write' permission for the asset type (of the asset which has the uploaded document)." } }, "summary" : "Removes an uploaded document.", "tags" : [ "Uploads" ] } } }, "components" : { "schemas" : { "Action" : { "type" : "object", "properties" : { "id" : { "type" : "string" }, "name" : { "type" : "string" } } }, "AssetData" : { "type" : "object", "description" : "A flat json object representing a single asset. The keys are field IDs (\"id\" and any fields requested using the \"field\" query parameter), and the values are the asset's values for those fields.", "properties" : { "id" : { "type" : "string", "format" : "uuid", "example" : "92d16369-e1ac-4b7a-b659-a4967160a43c" }, "name" : { "type" : "string", "example" : "PC 001" } } }, "AssetLinkRequest" : { "type" : "object", "description" : "Directional link to be added between two assets", "properties" : { "capabilityId" : { "type" : "string", "format" : "uuid", "description" : "The ID of the link type that is offered through the link. Don't specify it for parent-child relations.", "example" : "e462d679-aec2-4cc8-b81d-09236de4c198" }, "sourceId" : { "type" : "string", "format" : "uuid", "description" : "The ID of the asset to be the source of the link. For a child relation, this will be the parent, for a parent relation, this will be the child. For link types, this asset will provide the link type.", "example" : "1701c6f4-f5a4-438b-a1a8-50e9ebe1e5ae" }, "targetId" : { "type" : "string", "format" : "uuid", "description" : "The ID of the asset to be the target of the link. For a child relation, this will be the child, for a parent relation, this will be the parent. For link types, this asset will use the link type.", "example" : "aa6712d9-da6a-4393-bf12-6002b8b1c1fc" }, "type" : { "type" : "string", "default" : "child", "description" : "Defines the direction of the relation. 'child' means the 'target' is the child of the 'source'. 'child' is the default value. Ignored if a capabilityId is present.", "enum" : [ "parent", "child" ], "example" : "parent" } }, "required" : [ "sourceId", "targetId" ] }, "AssetListOperationRequest" : { "type" : "object", "properties" : { "unids" : { "type" : "array", "description" : "List of asset identifiers.", "items" : { "type" : "string", "format" : "uuid" } } }, "required" : [ "unids" ] }, "AssetResults" : { "type" : "object", "properties" : { "results" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/AssetData" } } } }, "AssetStatus" : { "type" : "object", "description" : "A flat json object representing a single asset status.", "properties" : { "id" : { "type" : "string", "description" : "The internal identifier of the asset status", "example" : "OPERATIONAL" }, "name" : { "type" : "string", "description" : "The translated display name of the asset status (if requested using the \"field\" query parameter)", "example" : "Operational" } } }, "AssetStatusResults" : { "type" : "object", "properties" : { "results" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/AssetStatus" } } } }, "AssetTemplateStructure" : { "type" : "object", "description" : "Structure of the template", "properties" : { "required" : { "type" : "array", "description" : "List of the names of the mandatory fields.", "items" : { "type" : "string" } }, "tabs" : { "type" : "array", "description" : "Tabs of the template (currently only one tab is supported)", "items" : { "$ref" : "#/components/schemas/TemplateTab" } } }, "required" : [ "tabs" ] }, "AssignmentLinkResponse" : { "type" : "object", "description" : "Links between the requested assignment and assets.", "properties" : { "branch" : { "$ref" : "#/components/schemas/Branch" }, "linkedObjectType" : { "type" : "string", "description" : "Type of linked assignment." }, "links" : { "type" : "array", "description" : "Information about the links created.", "items" : { "$ref" : "#/components/schemas/LinkResponse" } }, "location" : { "$ref" : "#/components/schemas/Location" }, "person" : { "$ref" : "#/components/schemas/Person" }, "personGroup" : { "$ref" : "#/components/schemas/PersonGroup" } } }, "AssignmentRequest" : { "type" : "object", "properties" : { "branchId" : { "type" : "string", "format" : "uuid", "description" : "If location is being linked, this ID can also be provided as the parent branch ID of the location. Otherwise its value is looked up automatically." }, "linkToId" : { "type" : "string", "format" : "uuid", "description" : "ID of the assigned entity." }, "linkType" : { "type" : "string", "description" : "Type of the assigned entity.", "enum" : [ "location", "branch", "person", "personGroup" ] } }, "required" : [ "linkToId", "linkType" ] }, "BadRequestEntity" : { "type" : "object", "properties" : { "errors" : { "type" : "array", "description" : "A list of errors.", "items" : { "$ref" : "#/components/schemas/BadRequestErrorDescription" } } }, "required" : [ "errors" ] }, "BadRequestErrorDescription" : { "type" : "object", "properties" : { "appliesTo" : { "type" : "array", "description" : "A list of fields that the error applies to. A field may be a query parameter, or a JSON property. If the field refers to a nested JSON property, the nested structure is included. In case an error is not bound to a property then the list is empty.", "example" : "[pageSize]", "items" : { "type" : "string" } }, "detail" : { "type" : "string", "description" : "Additional, human-readable information about the error", "example" : "pageSize must be between 0 and 42, both inclusive" }, "errorCode" : { "type" : "string", "description" : "A descriptive, human- and machine-readable error code", "example" : "value_too_small" } }, "required" : [ "errorCode" ] }, "BasicBranch" : { "type" : "object", "description" : "The branch assigned to the stock, if any. If a location is assigned to the stock, then the value is the branch of the location.", "nullable" : true, "properties" : { "id" : { "type" : "string", "format" : "uuid", "description" : "The unique identifier of the branch.", "example" : "a9e88454-82a9-43ac-a2ab-ff498d8b8f91" }, "name" : { "type" : "string", "description" : "The display name of the branch.", "example" : "TOPdesk Hungary Ltd." } }, "required" : [ "id", "name" ] }, "BasicBulkItem" : { "type" : "object", "description" : "The bulk item linked to the stock.", "properties" : { "id" : { "type" : "string", "format" : "uuid", "description" : "The unique identifier of the bulk item.", "example" : "e4a18843-0e30-4f06-afbc-deb22ee93059" }, "name" : { "type" : "string", "description" : "The display name of the bulk item.", "example" : "Red Pens" }, "template" : { "$ref" : "#/components/schemas/BasicBulkItemTemplate" } }, "required" : [ "id", "name", "template" ] }, "BasicBulkItemTemplate" : { "type" : "object", "description" : "The template of the bulk item.", "properties" : { "icon" : { "type" : "string", "description" : "The icon of the bulk item template.", "example" : "pen_icon", "nullable" : true }, "name" : { "type" : "string", "description" : "The display name of the bulk item template.", "example" : "Pens" } }, "required" : [ "name" ] }, "BasicLocation" : { "type" : "object", "description" : "The location assigned to the stock, if any.", "nullable" : true, "properties" : { "id" : { "type" : "string", "format" : "uuid", "description" : "The unique identifier of the location.", "example" : "cd596c36-b445-4a10-97ca-98e21226cc32" }, "name" : { "type" : "string", "description" : "The display name of the location.", "example" : "Room 42" } }, "required" : [ "id", "name" ] }, "BasicStockWithAssignmentInfo" : { "type" : "object", "description" : "The stock containing a certain amount of the bulk item.", "properties" : { "branch" : { "$ref" : "#/components/schemas/BasicBranch" }, "icon" : { "type" : "string", "description" : "The icon of the stock template.", "example" : "stock" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The unique identifier of the stock.", "example" : "f386943b-6039-4ecc-bc20-402b94bf7478" }, "location" : { "$ref" : "#/components/schemas/BasicLocation" }, "name" : { "type" : "string", "description" : "The display name of the stock.", "example" : "IT Stock" } }, "required" : [ "icon", "id", "name" ] }, "BasicTargetData" : { "type" : "object", "description" : "Contains basic information about the asset type or bulk item.", "properties" : { "archived" : { "type" : "boolean", "description" : "Archival state of the target" }, "icon" : { "type" : "string", "description" : "Name of the icon for the target." }, "id" : { "type" : "string", "format" : "uuid", "description" : "Identifier of the target." }, "name" : { "type" : "string", "description" : "Display name of the target." }, "type" : { "type" : "string", "description" : "Type of the target." } }, "required" : [ "archived", "icon", "id", "name", "type" ] }, "Branch" : { "type" : "object", "description" : "Properties of the linked branch", "properties" : { "archived" : { "type" : "boolean", "description" : "Whether the branch is archived" }, "id" : { "type" : "string", "description" : "Id of the branch" }, "name" : { "type" : "string", "description" : "Name of the branch" }, "specification" : { "type" : "string", "description" : "'specification' property of the branch" } }, "required" : [ "id", "name" ] }, "BulkAssignmentRequest" : { "type" : "object", "properties" : { "assetIds" : { "type" : "array", "description" : "List of assets/stocks/bulk items to be linked.", "items" : { "type" : "string", "format" : "uuid" }, "maxItems" : 50, "minItems" : 1 }, "branchId" : { "type" : "string", "format" : "uuid", "description" : "If location is being linked, this ID can also be provided as the parent branch ID of the location. Otherwise its value is looked up automatically." }, "linkToId" : { "type" : "string", "format" : "uuid", "description" : "ID of the assigned entity." }, "linkType" : { "type" : "string", "description" : "Type of the assigned entity.", "enum" : [ "location", "branch", "person", "personGroup" ] } }, "required" : [ "assetIds", "linkToId", "linkType" ] }, "BulkItemInStockRequest" : { "type" : "object", "description" : "Quantity and identifiers of the to be linked stock and bulk item.", "properties" : { "bulkItemId" : { "type" : "string", "format" : "uuid", "description" : "ID of bulk item", "example" : "e4a18843-0e30-4f06-afbc-deb22ee93059" }, "quantity" : { "type" : "integer", "format" : "int32", "default" : 0, "description" : "Quantity of bulk item in stock. Negative values are rejected.", "example" : 42, "minimum" : 0 }, "stockId" : { "type" : "string", "format" : "uuid", "description" : "ID of stock", "example" : "f386943b-6039-4ecc-bc20-402b94bf7478" } }, "required" : [ "bulkItemId", "stockId" ] }, "BulkLinkResponse" : { "type" : "object", "properties" : { "results" : { "type" : "array", "description" : "Information about the created links", "items" : { "$ref" : "#/components/schemas/LinkResponse" } } } }, "CapabilityCreateRequest" : { "type" : "object", "properties" : { "name" : { "type" : "string" } }, "required" : [ "name" ] }, "CapabilityDto" : { "type" : "object", "properties" : { "@etag" : { "type" : "string", "description" : "ETag for the given entity. It is used for concurrent modification checking with optimistic locking.", "example" : "2024-10-02T14:49:40.415" }, "archiveReasonId" : { "type" : "string", "format" : "uuid" }, "archived" : { "type" : "boolean" }, "inUse" : { "type" : "boolean" }, "inheritance" : { "$ref" : "#/components/schemas/Inheritance" }, "name" : { "type" : "string" }, "unid" : { "type" : "string", "format" : "uuid" } } }, "CapabilityEditRequest" : { "type" : "object", "properties" : { "@etag" : { "type" : "string", "description" : "ETag for the given entity. It is used for concurrent modification checking with optimistic locking.", "example" : "2024-10-02T14:49:40.415" }, "inheritance" : { "$ref" : "#/components/schemas/Inheritance" }, "name" : { "type" : "string", "description" : "the new name" } } }, "CapabilityListResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "List of link types", "items" : { "$ref" : "#/components/schemas/DataSetItem" } } }, "required" : [ "dataSet" ] }, "CardType" : { "type" : "object", "description" : "An asset template represents a type of card in the Asset Management module.", "properties" : { "displayName" : { "type" : "string", "description" : "The name of the asset template.", "example" : "Computer" }, "fields" : { "type" : "array", "description" : "The fields that are present on the asset template.", "items" : { "$ref" : "#/components/schemas/Field" } }, "key" : { "type" : "string", "description" : "The ID of the asset template.", "example" : "5c4b27a7-4849-453b-a0fc-129a740ddabb" }, "operations" : { "$ref" : "#/components/schemas/CardTypeOperations" }, "permissions" : { "$ref" : "#/components/schemas/ImportPermissions" } } }, "CardTypeOperations" : { "type" : "object", "description" : "Urls for the API operations available for the asset template.", "properties" : { "archive" : { "type" : "string", "description" : "The url to archive an asset of this type, where the client should replace '{id}' by the asset ID.", "example" : "/assetmgmt/assets/templateId/5c4b27a7-4849-453b-a0fc-129a740ddabb/{id}/archive" }, "create" : { "type" : "string", "description" : "The url to create a new asset of this type.", "example" : "/assetmgmt/assets/templateId/5c4b27a7-4849-453b-a0fc-129a740ddabb" }, "getList" : { "type" : "string", "description" : "The url to retrieve a list of all assets of this type.", "example" : "/assetmgmt/assets/templateId/5c4b27a7-4849-453b-a0fc-129a740ddabb" }, "modify" : { "type" : "string", "description" : "The url to modify an asset of this type, where the client should replace '{id}' by the asset ID.", "example" : "/assetmgmt/assets/templateId/5c4b27a7-4849-453b-a0fc-129a740ddabb/{id}" }, "open" : { "type" : "string", "description" : "The url to open an asset card of this type, where the client should replace '{id}' by the asset ID.", "example" : "/tas/secure/assetmgmt/card.html?unid={id}" } } }, "CardTypes" : { "type" : "object", "properties" : { "cardTypes" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/CardType" } } } }, "CopyAssetRequest" : { "type" : "object", "properties" : { "numberOfCopies" : { "type" : "integer", "format" : "int32" }, "prefix" : { "type" : "string" }, "startAt" : { "type" : "string" } } }, "CopyAssetResponse" : { "type" : "object", "properties" : { "creationDate" : { "type" : "string", "description" : "API-level creationDate of this response" }, "name" : { "type" : "string", "description" : "API-level name of this response" }, "unid" : { "type" : "string", "format" : "uuid", "description" : "API-level unid of this response" } }, "required" : [ "creationDate", "name", "unid" ] }, "CopyAssetResponseList" : { "type" : "object", "properties" : { "dataset" : { "type" : "array", "description" : "Data set of the result assets. Each asset is represented as key/value pairs of fieldNames and field values", "items" : { "$ref" : "#/components/schemas/CopyAssetResponse" } } }, "required" : [ "dataset" ] }, "CreatedAsset" : { "type" : "object", "description" : "A flat json object representing the created asset.", "properties" : { "id" : { "type" : "string", "format" : "uuid", "description" : "The ID of the created asset.", "example" : "2c95e63c-0bd7-492f-b21c-68b097f7ba08" } } }, "DataSetItem" : { "type" : "object", "properties" : { "archived" : { "type" : "boolean", "description" : "If 'true' denotes that the item is archived" }, "functionalities" : { "type" : "array", "description" : "Possible operations for the current data set item, filtered by the permissions of the current user.", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } }, "icon" : { "type" : "string", "description" : "Displayable icon for the item if applicable" }, "id" : { "type" : "string", "description" : "Identifier of the item" }, "inheritance" : { "$ref" : "#/components/schemas/Inheritance" }, "properties" : { "type" : "object", "description" : "Additional properties for the item" }, "text" : { "type" : "string", "description" : "Displayable text for the item" } }, "required" : [ "id", "text" ] }, "DatasetSuggestFieldOptionPropertiesResponse" : { "type" : "object", "description" : "Properties for dataset suggest field", "properties" : { "optionListType" : { "type" : "string", "description" : "Type of the option list", "enum" : [ "persons", "operators", "supplier", "budgetholder", "branch", "location", "location-with-room" ], "example" : "persons" } }, "required" : [ "optionListType" ] }, "DateFieldPropertiesResponse" : { "type" : "object", "description" : "Properties for date fields", "properties" : { "showTime" : { "type" : "boolean", "description" : "Indicates if time (as hours and minutes) should be displayed" } } }, "DeleteAssetsResponse" : { "type" : "object", "properties" : { "deleted" : { "type" : "array", "description" : "List of IDs of deleted assets.", "items" : { "type" : "string", "format" : "uuid" } }, "failed" : { "type" : "array", "description" : "List of IDs of assets which couldn't be deleted.", "items" : { "type" : "string", "format" : "uuid" } }, "missing" : { "type" : "array", "description" : "List of IDs of assets which weren't present.", "items" : { "type" : "string", "format" : "uuid" } }, "unauthorized" : { "type" : "array", "description" : "List of IDs of assets which user did not have enough permission to delete.", "items" : { "type" : "string", "format" : "uuid" } } } }, "DeleteGridAssetResponse" : { "type" : "object", "properties" : { "deleted" : { "type" : "array", "description" : "List of IDs of deleted assets.", "items" : { "type" : "string", "format" : "uuid" } }, "etag" : { "type" : "string" }, "failed" : { "type" : "array", "description" : "List of IDs of assets which couldn't be deleted.", "items" : { "type" : "string", "format" : "uuid" } }, "missing" : { "type" : "array", "description" : "List of IDs of assets which weren't present.", "items" : { "type" : "string", "format" : "uuid" } }, "unauthorized" : { "type" : "array", "description" : "List of IDs of assets which user did not have enough permission to delete.", "items" : { "type" : "string", "format" : "uuid" } } } }, "DropdownOption" : { "type" : "object", "description" : "A flat json object representing a single dropdown option. The keys are field IDs (\"id\", and \"name\" if requested using the \"field\" query parameter), and the values are the dropdown option's values for those fields.", "properties" : { "id" : { "type" : "string", "format" : "uuid", "example" : "877b131e-22f6-47b3-9029-702f13a72fca" }, "name" : { "type" : "string", "example" : "Option 1" } } }, "DropdownOptionId" : { "type" : "object", "description" : "An object representing the ID of a dropdown option.", "properties" : { "id" : { "type" : "string", "format" : "uuid", "description" : "The ID of the dropdown option.", "example" : "877b131e-22f6-47b3-9029-702f13a72fca" } } }, "DropdownOptionName" : { "type" : "object", "description" : "An object representing the name of a dropdown option.", "properties" : { "name" : { "type" : "string", "description" : "The name of the dropdown option.", "example" : "Option 1" } }, "required" : [ "name" ] }, "DropdownOptionResults" : { "type" : "object", "properties" : { "results" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/DropdownOption" } } } }, "ErrorDescription" : { "type" : "object", "properties" : { "appliesTo" : { "type" : "array", "description" : "A list of fields that the error applies to. A field may be a query parameter, or a JSON property. If the field refers to a nested JSON property, the nested structure is included. In case an error is not bound to a property then the list is empty.", "example" : [ "pageSize" ], "items" : { "type" : "string" } }, "errorCode" : { "type" : "string", "description" : "A descriptive, human- and machine-readable error code", "example" : "value_too_small" }, "errorMessage" : { "type" : "string", "description" : "Additional, human-readable information about the error", "example" : "pageSize must be between 0 and 42, both inclusive" } }, "required" : [ "appliesTo", "errorCode" ] }, "ErrorResponseEntity" : { "type" : "object", "properties" : { "errors" : { "type" : "array", "description" : "A list of errors.", "items" : { "$ref" : "#/components/schemas/ErrorDescription" } } }, "required" : [ "errors" ] }, "ExampleCopyModel" : { "type" : "object", "properties" : { "numberOfCopies" : { "type" : "integer", "format" : "int32", "description" : "Number of copies to create.", "example" : 42 }, "prefix" : { "type" : "string", "description" : "Prefix of the newly created assets. Needs to be provided only when auto numbering is turned off.", "example" : "PC" }, "startAt" : { "type" : "string", "description" : "The number of the first copy. The asset ids of the following copies will be generated by increasing this number.", "example" : "042" } }, "required" : [ "numberOfCopies" ] }, "ExampleCreateModel" : { "type" : "object", "properties" : { "dateField" : { "type" : "string", "description" : "A date field example", "example" : "2024-10-02T12:52:21.260" }, "dropdownField" : { "type" : "string", "description" : "A dropdown field example", "example" : "AF404E17-F1E3-4AB7-BB77-F9FC5189CF6E" }, "numberField" : { "type" : "string", "description" : "A number field example", "example" : "15.44" }, "textField" : { "type" : "string", "description" : "A text field example", "example" : "Sample text" }, "type_id" : { "type" : "string", "description" : "The ID of the template", "example" : "A72B24C1-0553-4F88-9ADD-5B5BB85C7D4E" } }, "required" : [ "type_id" ] }, "ExampleDeleteModel" : { "type" : "object", "properties" : { "@etag" : { "type" : "string", "description" : "Current valid etag for the asset card.", "example" : "2026-08-25T11:15:26.819" }, "@gridwidgetfield_56246ce8-df66-4e07-bf90-b1df9928dae4" : { "type" : "string", "description" : "There is a dynamic property which represents the actual dataset widget (its key starts with `@gridwidgetfield`). The corresponding value to this dynamic property contains the IDs of the remaining rows, without the IDs of the deleted rows. This is a string which contains a stringified and correctly escaped value of a JSON array.", "example" : "[\"75a5b8d6-348b-49d7-b3f9-958feece8a68\"]" }, "unid" : { "type" : "string", "description" : "ID of the asset card.", "example" : "aa6712d9-da6a-4393-bf12-6002b8b1c1fc" } }, "required" : [ "@etag", "@gridwidgetfield_56246ce8-df66-4e07-bf90-b1df9928dae4", "unid" ] }, "ExampleSaveModel" : { "type" : "object", "properties" : { "@etag" : { "type" : "string", "description" : "ETag for the given entity. It is used for concurrent modification checking with optimistic locking.", "example" : "2024-10-02T14:49:40.415" }, "@status" : { "type" : "string", "description" : "Status shows if this asset is operational right now or not. Main field to set for triggering Impact Analysis features.", "enum" : [ "OPERATIONAL", "IMPACTED" ], "example" : "OPERATIONAL" }, "@statusLocked" : { "type" : "boolean", "description" : "Enterprise users can enable automatic propagation by setting @statusLocked to false, or stop automatic propagation and enable manual status switching by setting @statusLocked to true.", "example" : true }, "dateField" : { "type" : "string", "description" : "A date field example", "example" : "2024-10-02T12:52:21.260" }, "dropdownField" : { "type" : "string", "description" : "A dropdown field example", "example" : "AF404E17-F1E3-4AB7-BB77-F9FC5189CF6E" }, "numberField" : { "type" : "string", "description" : "A number field example", "example" : "15.44" }, "textField" : { "type" : "string", "description" : "A text field example", "example" : "Sample text" } } }, "Field" : { "type" : "object", "properties" : { "defaultUniqueKey" : { "type" : "boolean", "description" : "Set this to true if the field is the default unique identifier for the card.", "example" : false }, "displayName" : { "type" : "string", "description" : "The label of the field.", "example" : "Assignment widget - Persons" }, "key" : { "type" : "string", "description" : "The field ID of the field.", "example" : "@@assignment_persons" }, "operations" : { "$ref" : "#/components/schemas/ForeignKeyOperations" }, "readOnly" : { "type" : "boolean", "description" : "Whether the field is read-only.", "example" : false }, "required" : { "type" : "boolean", "description" : "Whether the field is required.", "example" : false }, "type" : { "type" : "string", "description" : "The type of the field.", "enum" : [ "BOOLEAN", "NUMBER", "STRING", "DATE", "FOREIGN_KEY", "FOREIGN_KEY_LIST" ], "example" : "FOREIGN_KEY_LIST" } } }, "FieldDefinitionListResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "List of fields", "items" : { "$ref" : "#/components/schemas/FieldDefinitionResponseItem" } } }, "required" : [ "dataSet" ] }, "FieldDefinitionResponseItem" : { "type" : "object", "description" : "Contains information about a field", "properties" : { "archived" : { "type" : "boolean", "description" : "The value 'true' denotes that the field doesn't occur on any template" }, "icon" : { "type" : "string", "description" : "Displayable icon for the field if applicable" }, "id" : { "type" : "string", "description" : "Identifier of the field" }, "properties" : { "type" : "object", "additionalProperties" : { "type" : "object", "description" : "Additional properties for the field" }, "description" : "Additional properties for the field" }, "text" : { "type" : "string", "description" : "Displayable text for the field" } }, "required" : [ "id", "text" ] }, "FieldListResponse" : { "type" : "object", "description" : "Response for getting field list.", "properties" : { "fields" : { "type" : "array", "description" : "List of fields.", "items" : { "$ref" : "#/components/schemas/FieldWithInUse" } } } }, "FieldResponse" : { "type" : "object", "description" : "Response for a field resource", "properties" : { "etag" : { "type" : "string", "description" : "ETag for concurrency control", "example" : "2024-10-07T12:44:14.214" }, "fieldType" : { "type" : "string", "description" : "Type of the field", "enum" : [ "textField", "numberField", "dateTimeField", "checkboxField", "suggestField" ], "example" : "numberField" }, "functionalities" : { "type" : "array", "description" : "Possible operations for the current field, filtered by the permissions of the current user", "items" : { "$ref" : "#/components/schemas/Functionality" } }, "id" : { "type" : "string", "description" : "ID of the field", "example" : "field-id" }, "name" : { "type" : "string", "description" : "Name of the field", "example" : "Example number field" }, "properties" : { "$ref" : "#/components/schemas/PropertiesResponse" } } }, "FieldWithInUse" : { "type" : "object", "description" : "Response for a field resource", "properties" : { "etag" : { "type" : "string", "description" : "ETag for concurrency control", "example" : "2024-10-07T12:44:14.214" }, "fieldType" : { "type" : "string", "description" : "Type of the field", "enum" : [ "textField", "numberField", "dateTimeField", "checkboxField", "suggestField" ], "example" : "numberField" }, "id" : { "type" : "string", "description" : "ID of the field", "example" : "field-id" }, "inUse" : { "type" : "boolean", "description" : "Shows if the field is in use in any of the templates", "example" : true }, "name" : { "type" : "string", "description" : "Name of the field", "example" : "Example number field" }, "properties" : { "$ref" : "#/components/schemas/PropertiesResponse" } } }, "File" : { "type" : "object", "properties" : { "created" : { "type" : "string", "description" : "The date of the creation" }, "creatorId" : { "type" : "string", "description" : "The ID of the user, who created (uploaded) the file" }, "id" : { "type" : "string", "description" : "The upload ID" }, "lengthInBytes" : { "type" : "integer", "format" : "int64", "description" : "The length of the file in bytes" }, "name" : { "type" : "string", "description" : "The name of the file" }, "operator" : { "$ref" : "#/components/schemas/Operator" }, "url" : { "type" : "string", "description" : "The url, where the file can be downloaded" } }, "required" : [ "created", "creatorId", "id", "lengthInBytes", "name", "operator", "url" ] }, "ForeignKeyOperations" : { "type" : "object", "description" : "Urls for the API operations available for a foreign key (only if type is 'FOREIGN_KEY' or 'FOREIGN_KEY_LIST').", "properties" : { "getCardType" : { "type" : "string", "description" : "The url to retrieve information about this type (including name, ID, fields and API operations).", "example" : "/tas/api/import/supportingFiles/cardTypes/person" }, "link" : { "type" : "string", "description" : "The url to link entries of this type to an asset (only if the field type is 'FOREIGN_KEY_LIST').", "example" : "/tas/api/assetmgmt/assets/templateId/5c4b27a7-4849-453b-a0fc-129a740ddabb/{id}/assignment/persons" } } }, "FrontendAsset" : { "type" : "object", "properties" : { "data" : { "type" : "object", "description" : "Asset data itself as a key/value map. It contains the field values by fieldName and also some extra entries related to other features, like: @status, @etag" }, "fields" : { "type" : "object", "description" : "Definitions of the fields of the asset data" }, "functionalities" : { "type" : "array", "description" : "Possible operations for the current asset, filtered by the permissions of the current user", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } }, "metadata" : { "$ref" : "#/components/schemas/FrontendMetadata" }, "settings" : { "type" : "object", "description" : "Various settings which might be useful to display the data" } }, "required" : [ "data" ] }, "FrontendCapability" : { "type" : "object", "properties" : { "capability" : { "$ref" : "#/components/schemas/CapabilityDto" }, "functionalities" : { "type" : "array", "description" : "Possible operations for the current link type, filtered by the permissions of the current user", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } } } }, "FrontendFieldDefinition" : { "type" : "object", "properties" : { "@etag" : { "type" : "string", "description" : "ETag for the given entity. It is used for concurrent modification checking with optimistic locking.", "example" : "2024-10-02T14:49:40.415" }, "displayName" : { "type" : "string", "description" : "Displayable name of the field" }, "fieldName" : { "type" : "string", "description" : "API-level name of the field" }, "fieldType" : { "type" : "string", "description" : "Type of the field" }, "functionalities" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } }, "properties" : { "type" : "object", "description" : "Field-specific properties" }, "resourceKey" : { "type" : "string", "description" : "Resourcekey for the displayname" }, "sortable" : { "type" : "boolean", "description" : "If true, the data set in the GET /assets endpoint response can be sorted by this field, using the $orderby request parameter." }, "valueType" : { "type" : "string", "description" : "Type of the value stored in the field", "enum" : [ "BOOL", "NUMBER", "DATE", "TEXT", "ID", "ID_LIST", "COMPLEX", "NOTFIELD" ] } }, "required" : [ "fieldName" ] }, "FrontendMetadata" : { "type" : "object", "description" : "Metadata about the asset, including field types, field display names, etc.", "properties" : { "@etag" : { "type" : "string", "description" : "ETag for the given entity. It is used for concurrent modification checking with optimistic locking.", "example" : "2024-10-02T14:49:40.415" }, "archived" : { "type" : "boolean", "description" : "Archived state of the template" }, "autoNumbering" : { "$ref" : "#/components/schemas/TemplateAutonumbering" }, "defaultTemplateName" : { "type" : "string", "description" : "Default name of the template" }, "functionalities" : { "type" : "array", "description" : "Possible operations for the current template, filtered by the permissions of the current user", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } }, "icon" : { "$ref" : "#/components/schemas/TemplateIcon" }, "resourceCategory" : { "type" : "string", "description" : "Resource category of the template" }, "settings" : { "$ref" : "#/components/schemas/TemplateSettings" }, "template" : { "$ref" : "#/components/schemas/AssetTemplateStructure" }, "templateId" : { "type" : "string", "description" : "Unique identifier of the template" }, "templateName" : { "type" : "string", "description" : "Name of the template" } }, "required" : [ "archived", "template", "templateId", "templateName" ] }, "FrontendValidationProblem" : { "type" : "object", "properties" : { "fieldName" : { "type" : "string", "description" : "API-level field name" }, "fieldTitle" : { "type" : "string", "description" : "Field's display name" }, "message" : { "type" : "string", "description" : "Validation error message" } } }, "Functionality" : { "type" : "object", "properties" : { "enabled" : { "type" : "boolean", "description" : "A false value is included if it's disabled, otherwise nothing is included.", "example" : false, "nullable" : true }, "name" : { "type" : "string", "description" : "Name of the functionality", "example" : "delete" } }, "required" : [ "name" ] }, "GridAssetStructureResponse" : { "type" : "object", "properties" : { "columns" : { "type" : "array", "description" : "List of field-definitions of the contained columns", "items" : { "$ref" : "#/components/schemas/FrontendFieldDefinition" } }, "count" : { "type" : "integer", "format" : "int64", "description" : "The number of assets that match the filtering criteria. Available only when fetchCount (if supported by the endpoint) is set to true" }, "dataSet" : { "type" : "array", "description" : "Data set of the result assets. Each asset is represented as key/value pairs of fieldNames and field values", "items" : { "type" : "object" } }, "functionalities" : { "type" : "array", "description" : "Possible operations for the asset, filtered by the permissions of the current user", "items" : { "$ref" : "#/components/schemas/SimpleFunctionality" } }, "resources" : { "type" : "object", "description" : "Resource / resourcekey mappings (This will be deprecated soon)" }, "settings" : { "type" : "object", "description" : "Various settings which might be useful to display the data" }, "templates" : { "type" : "array", "description" : "Template information - this will be populated when includeTemplates is mentioned in the request", "items" : { "$ref" : "#/components/schemas/DataSetItem" } } }, "required" : [ "columns", "dataSet" ] }, "HistoryItem" : { "type" : "object", "description" : "Represents one event. Based on the nature of the particular event this object can have different properties.", "properties" : { "actor" : { "type" : "string", "description" : "Displayable name of the user who initiated this event." }, "assignment" : { "type" : "object", "description" : "Only for assignments: contains the old and new value of the assignment." }, "callerId" : { "type" : "string", "description" : "For some of the logged-card related events, the ID of the caller." }, "date" : { "type" : "string", "format" : "date-time", "description" : "Millisec precision UTC timestamp of the event." }, "field" : { "type" : "object", "description" : "Only for field changes: contains the old and new value of the field." }, "files" : { "type" : "object", "description" : "Only for document upload event: contains data about the uploaded or deleted files." }, "id" : { "type" : "string", "description" : "Only for internal events: internal ID of the given event." }, "inheritanceParent" : { "$ref" : "#/components/schemas/InheritanceParent" }, "number" : { "type" : "string", "description" : "Human-readable identifier of the linked card." }, "operatorId" : { "type" : "string", "description" : "Id of the user who initiated this event (not available for all event types)." }, "summary" : { "type" : "string", "description" : "Short summary which is related to this event. It might contain 'brief description' content of the linked card." }, "type" : { "type" : "string", "description" : "Type of the event." } } }, "HistoryItemCollection" : { "type" : "object", "properties" : { "items" : { "type" : "array", "description" : "List of items.", "items" : { "$ref" : "#/components/schemas/HistoryItem" } }, "next" : { "type" : "string", "description" : "Link to the next page of items if there are more items then what fits into the response page size." } } }, "IdList" : { "type" : "object", "properties" : { "ids" : { "type" : "array", "description" : "A list of IDs of the entities to link.", "items" : { "type" : "string", "format" : "uuid" } } } }, "ImportPermissions" : { "type" : "object", "description" : "The Import-to-API permissions of the current operator related to the asset template", "properties" : { "executeImports" : { "type" : "boolean", "description" : "A boolean specifying whether the current operator is allowed to execute imports for this card type", "example" : false } } }, "Inheritance" : { "type" : "object", "description" : "Inheritance settings", "properties" : { "location" : { "type" : "boolean" }, "person" : { "type" : "boolean" } } }, "InheritanceParent" : { "type" : "object", "description" : "Only for inherited assignments: contains data about the parent asset where the assignment is inherited from.", "properties" : { "iconId" : { "type" : "string" }, "id" : { "type" : "string", "format" : "uuid" }, "name" : { "type" : "string" } } }, "LinkError" : { "type" : "object", "properties" : { "errorCode" : { "type" : "string", "enum" : [ "value_unknown", "unknown_error" ], "example" : "value_unknown" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The ID of the entity to be assigned that caused the error." } } }, "LinkResponse" : { "type" : "object", "description" : "A link between the requested entity and an asset.", "properties" : { "assetId" : { "type" : "string", "format" : "uuid", "description" : "ID of the linked asset." }, "linkId" : { "type" : "string", "format" : "uuid", "description" : "ID of the link." } }, "required" : [ "assetId", "linkId" ] }, "LinkResults" : { "type" : "object", "properties" : { "linkErrors" : { "type" : "array", "description" : "A list of errors that occurred when linking entities.", "items" : { "$ref" : "#/components/schemas/LinkError" } }, "modified" : { "type" : "boolean", "description" : "Whether the links of the asset have actually changed as a result of this operation." }, "unlinkErrors" : { "type" : "array", "description" : "A list of errors that occurred when linking entities.", "items" : { "$ref" : "#/components/schemas/UnlinkError" } } } }, "LinkStatisticsItem" : { "type" : "object", "properties" : { "countOfLinkedResources" : { "type" : "integer", "format" : "int32", "description" : "Count of linked resources of the particular asset type or bulk item (generally, a resource) where the resource has 'target' role in links typed by the provided capability. (How many stocks contain at least one instance of this resource.)" }, "countOfLinks" : { "type" : "integer", "format" : "int32", "description" : "Count of links where the particular asset type or bulk item (generally, a resource) has 'target' role in the link typed by the provided capability. In case of bulk items, a link counts as many times as the quantity associated with that link. (How many instances are there in total of this resource in stock.)" }, "target" : { "$ref" : "#/components/schemas/BasicTargetData" } }, "required" : [ "countOfLinkedResources", "countOfLinks", "target" ] }, "LinkStatisticsResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "Data set of the result. Each item in the array represents statistics about one asset type or one bulk item. Items are sorted alphabetically by the display name of targets.", "items" : { "$ref" : "#/components/schemas/LinkStatisticsItem" } } }, "required" : [ "dataSet" ] }, "LinkedAsset" : { "type" : "object", "properties" : { "archived" : { "type" : "boolean", "description" : "Archive state of the link type" }, "archivedAsset" : { "type" : "boolean", "description" : "Archive state of the asset" }, "assetIcon" : { "$ref" : "#/components/schemas/TemplateIcon" }, "assetId" : { "type" : "string", "format" : "uuid", "description" : "ID of the linked asset", "example" : "1701c6f4-f5a4-438b-a1a8-50e9ebe1e5ae" }, "capabilityId" : { "type" : "string", "format" : "uuid", "description" : "ID of link type", "example" : "e462d679-aec2-4cc8-b81d-09236de4c198" }, "capabilityName" : { "type" : "string", "description" : "Name of link type", "example" : "Host" }, "linkId" : { "type" : "string", "format" : "uuid", "description" : "ID of the link" }, "linkType" : { "type" : "string", "description" : "Type of the link", "enum" : [ "child", "parent" ], "example" : "parent" }, "name" : { "type" : "string", "description" : "Name of the linked asset", "example" : "VM001" }, "status" : { "type" : "string", "description" : "Impact status of the asset.", "enum" : [ "OPERATIONAL", "IMPACTED" ] }, "summary" : { "type" : "string", "description" : "Summary of the asset", "example" : "Virtual Machine running on VMWare" }, "type" : { "type" : "string", "description" : "Type of the linked asset (name of its template)", "example" : "Virtual Machine" } }, "required" : [ "assetId", "linkId", "linkType", "name", "type" ] }, "Links" : { "type" : "object", "description" : "List of location and person links", "properties" : { "locations" : { "type" : "array", "description" : "List of locations or branches which are assigned to this asset", "items" : { "$ref" : "#/components/schemas/LocationLink" } }, "persons" : { "type" : "array", "description" : "List of persons or person groups which are assigned to this asset", "items" : { "$ref" : "#/components/schemas/PersonLink" } } }, "required" : [ "locations", "persons" ] }, "Location" : { "type" : "object", "description" : "Properties of the linked location", "properties" : { "archived" : { "type" : "boolean", "description" : "Whether the location is archived" }, "id" : { "type" : "string", "description" : "Id of the location" }, "name" : { "type" : "string", "description" : "Name of the location" }, "roomNumber" : { "type" : "string", "description" : "'roomNumber' property of the location" }, "specification" : { "type" : "string", "description" : "'specification' property of the location" } }, "required" : [ "id", "name" ] }, "LocationLink" : { "type" : "object", "properties" : { "branch" : { "$ref" : "#/components/schemas/Branch" }, "inheritanceParentId" : { "type" : "string", "format" : "uuid", "description" : "ID of the asset from which this location is inherited." }, "linkId" : { "type" : "string", "format" : "uuid", "description" : "ID of the link" }, "linkedObjectType" : { "type" : "string", "description" : "Type of the linked location", "enum" : [ "branch", "location" ] }, "location" : { "$ref" : "#/components/schemas/Location" } } }, "ManualTriggersResponse" : { "type" : "object", "properties" : { "actions" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Action" } } } }, "ModifiedAssetResponse" : { "type" : "object", "properties" : { "modified" : { "type" : "boolean", "description" : "Whether the asset has actually changed as a result of this operation." } } }, "NumberFieldPropertiesResponse" : { "type" : "object", "description" : "Properties for number fields", "properties" : { "decimals" : { "type" : "integer", "format" : "int32", "description" : "Number of decimal places", "example" : 5 }, "isCurrency" : { "type" : "boolean", "description" : "Indicates if the field represents currency", "example" : false }, "maxValue" : { "type" : "number", "format" : "double", "description" : "Indicates the maximum value of the field", "example" : 1000 }, "minValue" : { "type" : "number", "format" : "double", "description" : "Indicates the minimum value of the field", "example" : -10.5 } } }, "OneKnowledgeItemToManyAssetsRequest" : { "type" : "object", "properties" : { "assetIds" : { "type" : "array", "description" : "List of assets to be linked.", "items" : { "type" : "string", "format" : "uuid" }, "minLength" : 1 }, "knowledgeItemId" : { "type" : "string", "format" : "uuid", "description" : "ID of the knowledge item to be linked." } }, "required" : [ "assetIds", "knowledgeItemId" ] }, "OneServiceToManyAssetsRequest" : { "type" : "object", "properties" : { "assetIds" : { "type" : "array", "description" : "List of assets to be linked.", "items" : { "type" : "string", "format" : "uuid" }, "minLength" : 1 }, "serviceId" : { "type" : "string", "format" : "uuid", "description" : "ID of the service to be linked." } }, "required" : [ "assetIds", "serviceId" ] }, "OneTaskToManyAssetsRequest" : { "type" : "object", "properties" : { "assetIds" : { "type" : "array", "description" : "List of assets to be linked.", "items" : { "type" : "string", "format" : "uuid" }, "minLength" : 1 }, "taskId" : { "type" : "string", "format" : "uuid", "description" : "ID of the task to be linked. Its type is defined by taskType." }, "taskType" : { "type" : "string", "description" : "Type of the task to be linked.", "enum" : [ "change", "changeActivity", "incident", "omActivity", "omSeries", "problem" ] } }, "required" : [ "assetIds", "taskId", "taskType" ] }, "Operator" : { "type" : "object", "description" : "The operator, who uploaded the file", "properties" : { "dynamicName" : { "type" : "string", "description" : "The dynamic name of the operator" }, "id" : { "type" : "string", "description" : "The ID of the operator" } }, "required" : [ "dynamicName", "id" ] }, "OwnOptionsSuggestFieldOptionPropertiesResponse" : { "type" : "object", "description" : "Properties of an own option suggest field", "properties" : { "optionListId" : { "type" : "string", "format" : "uuid", "description" : "Option list id of the suggest field", "example" : "a248264a-d8aa-41f5-82fd-9e720c5c057f" }, "usersCanAddOptions" : { "type" : "boolean", "description" : "Indicates if users can add own options or not", "example" : true } }, "required" : [ "optionListId", "usersCanAddOptions" ] }, "Person" : { "type" : "object", "description" : "Properties of the assigned person.", "properties" : { "archived" : { "type" : "boolean", "description" : "Whether person is archived." }, "avatar" : { "type" : "string", "description" : "Picture/avatar of the person in data:image/base64 format." }, "branchName" : { "type" : "string", "description" : "Name of the branch which is associated with this person." }, "function" : { "type" : "string", "description" : "Function of the person." }, "id" : { "type" : "string", "description" : "Id of the person." }, "name" : { "type" : "string", "description" : "Full name of the person." } }, "required" : [ "id", "name" ] }, "PersonGroup" : { "type" : "object", "description" : "Properties of the assigned person group.", "properties" : { "archived" : { "type" : "boolean", "description" : "Whether person group is archived." }, "id" : { "type" : "string", "description" : "Id of the person group" }, "name" : { "type" : "string", "description" : "Name of the person group" } }, "required" : [ "id", "name" ] }, "PersonLink" : { "type" : "object", "properties" : { "inheritanceParentId" : { "type" : "string", "format" : "uuid", "description" : "ID of the asset from which this location is inherited." }, "linkId" : { "type" : "string", "format" : "uuid", "description" : "ID of the link" }, "linkedObjectType" : { "type" : "string", "description" : "Type of the linked entity", "enum" : [ "person", "personGroup" ] }, "person" : { "$ref" : "#/components/schemas/Person" }, "personGroup" : { "$ref" : "#/components/schemas/PersonGroup" } }, "required" : [ "linkId" ] }, "PropertiesResponse" : { "type" : "object", "description" : "Base interface for field properties", "oneOf" : [ { "$ref" : "#/components/schemas/NumberFieldPropertiesResponse" }, { "$ref" : "#/components/schemas/SuggestFieldPropertiesResponse" }, { "$ref" : "#/components/schemas/TextFieldPropertiesResponse" }, { "$ref" : "#/components/schemas/DateFieldPropertiesResponse" } ] }, "Reason" : { "type" : "object", "properties" : { "reasonId" : { "type" : "string", "format" : "uuid", "description" : "Reason ID which should be registered to the archived asset" } }, "required" : [ "reasonId" ] }, "ReasonForArchiving" : { "type" : "object", "properties" : { "reasonId" : { "type" : "string", "format" : "uuid", "description" : "The ID of the reason for archiving." } }, "required" : [ "reasonId" ] }, "SimpleFunctionality" : { "type" : "object", "properties" : { "name" : { "type" : "string", "description" : "API-level name of this functionality" }, "parameters" : { "type" : "object", "description" : "API-level parameters for this functionality" } }, "required" : [ "name" ] }, "StockQuantitiesItem" : { "type" : "object", "properties" : { "bulkItem" : { "$ref" : "#/components/schemas/BasicBulkItem" }, "etag" : { "type" : "string", "description" : "A hash value which is updated when quantity is updated." }, "id" : { "type" : "string", "format" : "uuid", "description" : "The unique identifier of the relation between a stock and a bulk item.", "example" : "fae8bc90-411c-4b35-a0b3-45abac451915" }, "quantity" : { "type" : "integer", "format" : "int32", "description" : "The amount of the bulk item in the stock.", "example" : 42, "minimum" : 0 }, "stock" : { "$ref" : "#/components/schemas/BasicStockWithAssignmentInfo" } }, "required" : [ "bulkItem", "etag", "id", "quantity", "stock" ] }, "StockQuantitiesResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "Data set of the result. Each item in the array represents the quantity of bulk items in a stock. Items are sorted alphabetically by the display name of stocks (when the bulk item is the same for each item) or bulk items (when the stock is the same for each item).", "items" : { "$ref" : "#/components/schemas/StockQuantitiesItem" } }, "total" : { "type" : "integer", "format" : "int32", "description" : "The number of results across all pages. Can be used to determine if there are more pages to visit.", "example" : 32 } }, "required" : [ "dataSet", "total" ] }, "StockQuantityUpdatePayload" : { "type" : "object", "description" : "The new value of the quantity for a given relation (between a stock and a bulk item).", "properties" : { "quantity" : { "type" : "integer", "format" : "int32", "description" : "Quantity of bulk item in stock. Negative values are rejected.", "example" : 42, "minimum" : 0 } }, "required" : [ "quantity" ] }, "SuggestFieldOptionPropertiesResponse" : { "type" : "object", "description" : "Base interface for suggest field option properties", "oneOf" : [ { "$ref" : "#/components/schemas/DatasetSuggestFieldOptionPropertiesResponse" }, { "$ref" : "#/components/schemas/OwnOptionsSuggestFieldOptionPropertiesResponse" } ] }, "SuggestFieldPropertiesResponse" : { "type" : "object", "properties" : { "optionProperties" : { "$ref" : "#/components/schemas/SuggestFieldOptionPropertiesResponse" }, "ownOptions" : { "type" : "boolean", "description" : "Indicates if the field has options defined by the user", "example" : true } } }, "TemplateAutonumbering" : { "type" : "object", "description" : "Autonumbering for the template", "properties" : { "enabled" : { "type" : "boolean", "description" : "Autonumbering enabled." }, "minLength" : { "type" : "integer", "format" : "int32", "description" : "Autonumbering minimum length." }, "prefix" : { "type" : "string", "description" : "Autonumbering prefix." }, "startIndex" : { "type" : "integer", "format" : "int32", "description" : "Autonumbering start index." } } }, "TemplateColumn" : { "type" : "object", "properties" : { "size" : { "type" : "string", "description" : "Size of the columns (their ratios to each other)", "enum" : [ "1-2", "2-1", "1-1" ] }, "widgets" : { "type" : "array", "description" : "Widgets of the column", "items" : { "$ref" : "#/components/schemas/Widget" } } }, "required" : [ "size", "widgets" ] }, "TemplateIcon" : { "type" : "object", "description" : "Icon of the linked asset's template", "properties" : { "id" : { "type" : "string", "description" : "Id for the icon", "example" : "virtual_machine" }, "name" : { "type" : "string", "description" : "Name for the icon", "example" : "vm" }, "url16" : { "type" : "string", "description" : "URL for 16-pixel variant", "example" : "/icons/vm/16" }, "url32" : { "type" : "string", "description" : "URL for 32-pixel variant", "example" : "/icons/vm/32" } }, "required" : [ "id" ] }, "TemplateListResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "List of templates as ID/name pairs", "items" : { "$ref" : "#/components/schemas/DataSetItem" } } }, "required" : [ "dataSet" ] }, "TemplateSettings" : { "type" : "object", "description" : "Settings for the template", "properties" : { "visibleOnSSP" : { "type" : "boolean" } } }, "TemplateTab" : { "type" : "object", "properties" : { "columns" : { "type" : "array", "description" : "Columns of the tab", "items" : { "$ref" : "#/components/schemas/TemplateColumn" } }, "resourceKey" : { "type" : "string", "description" : "Resourcekey of the tab" } }, "required" : [ "columns" ] }, "TextFieldPropertiesResponse" : { "type" : "object", "description" : "Properties for text fields", "properties" : { "maxLength" : { "type" : "integer", "format" : "int32", "description" : "Maximum length of the text stored" }, "multilineSupport" : { "type" : "boolean", "description" : "Indicates if multiline support is enabled" } } }, "UnlinkError" : { "type" : "object", "properties" : { "errorCode" : { "type" : "string", "enum" : [ "unknown_error" ], "example" : "unknown_error" }, "id" : { "type" : "string", "format" : "uuid", "description" : "The ID of the entity to be unassigned that caused the error." } } }, "UnlinkParameters" : { "type" : "object", "properties" : { "assetIds" : { "type" : "array", "description" : "List of assets to be unlinked.", "items" : { "type" : "string", "format" : "uuid" } } }, "required" : [ "assetIds" ] }, "UnlinkResponse" : { "type" : "object", "properties" : { "successful" : { "type" : "array", "description" : "List of the successfully unlinked assets", "items" : { "type" : "string", "format" : "uuid" } }, "summary" : { "type" : "string", "description" : "The summary of the unlinking" } }, "required" : [ "successful" ] }, "UploadResponse" : { "type" : "object", "properties" : { "dataSet" : { "type" : "array", "description" : "The list of the uploaded files' details", "items" : { "$ref" : "#/components/schemas/File" } } }, "required" : [ "dataSet" ] }, "ValidationErrorsResponse" : { "type" : "object", "properties" : { "errors" : { "type" : "array", "description" : "List of validation errors", "items" : { "$ref" : "#/components/schemas/FrontendValidationProblem" } } } }, "Widget" : { "type" : "object", "properties" : { "resourceKey" : { "type" : "string", "description" : "Resourcekey for the widget's title" }, "title" : { "type" : "string", "description" : "Title of the widget" } } } } } }