ItemMetadata OAPI

In Surpass, you can attach metadata (known as “tags”) to items and then use these tags to organise items when authoring content, creating tests, and viewing results. Tags are made up of “tag groups” and “tag values”.

Tags are made up of categorised containers called “tag groups” that contain individual tags called “tag values”. For example, a tag group called “difficulty” might have the following tag values: “Easy”, “Medium”, and “Hard”.

Enemy relationships are also a form of metadata in Surpass; when creating an item, you can set up enemy relationships with other items. Enemy items can never appear in the same test.

The ItemMetadata OAPI is used to update tags assigned to items and their enemy relationships. For information on tag groups and tag values, read TagGroup OAPI and TagValue OAPI.

This article explains what calls can be made to the Surpass OAPI using the ItemMetadata resource.

Import this API into your Postman Workspace

Updating an item and tag value association

put /oapi/ItemMetadata/ItemTags/{id}

Send a request to the endpoint to update an item and tag value association.

Parameters

Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
content-length	header MANDATORY	`{number}`	Determines the number of characters passed in the body of the request, where `{number}` is a numerical figure. This is usually automatically calculated when the request is sent.
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/ItemMetadata/ItemTags/{id}`	Updates item and tag value association for the specified item, where `{id}` is the item’s unique identifier.

Sample request

The following request contains the minimum required request body to update an item and tag value association.

{
    "tagGroups": [
        {
            "name": "Tag Group 1",
            "tagValues": [
                {
                    "value": "Tag Value 1"
                }
            ]
        }
    ]
}

EXAMPLE: In this sample request, ‘Tag Value 1’ from ‘Tag Group 1’ is assigned to the item specified in the request’s path parameter.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

tagGroups array

Contains the tag group’s information.

NOTE: To assign multiple tag values from multiple tag groups to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: To add the tag group to multiple tag categories, pass a separate object for each tag category.

tagGroups/tagCategories/id integer

The tag category’s unique identifier.

tagGroups/tagCategories/name string

The tag category’s name.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item and tag value association’s details.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Updating an item’s enemy relationship

put /oapi/ItemMetadata/ItemEnemies/{id}

Send a request to the endpoint to update an item’s enemy relationship.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
content-length	header MANDATORY	`{number}`	Determines the number of characters passed in the body of the request, where `{number}` is a numerical figure. This is usually automatically calculated when the request is sent.
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/ItemMetadata/ItemEnemies/{id}`	Updates an enemy relationship for the specified item, where `{id}` is the item’s unique identifier.

Sample request

The following request contains the minimum required request body to update an item and tag value association.

{
  "enemyItems": [
    {
      "id": 2
    }
  ]
}

EXAMPLE: In this sample request, item 1 is now an enemy item of the item specified in the request’s path parameter.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item and tag value association’s details.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Error Codes

Refer to the following table for information on error codes that may be encountered when using this resource.

Code	Description
400	Indicates one of the following issues: There is an issue with the query parameters. Item is locked by another user. Item cannot be updated.
401	The request has been sent by an unauthorised user.
403	Item cannot be accessed.
404	Item does not exist.

ItemMetadata OAPI

In This Article

Updating an item and tag value association

Parameters

Sample request

Request body schema

Sample response

Updating an item’s enemy relationship

Parameters

Sample request

Request body schema

Sample response

Error Codes

Further reading

About the site