Surpass Help Site
  • Skip to search
  • Skip to content
  • Surpass Platform
    • Surpass Platform Basics
    • Changelog (Resources)
    • Item Authoring
    • Surpass Copilot
    • Tasks
    • Reporting
    • Surpass Publisher
    • Test Wizard
    • Test Creation
    • Test Administration
    • Test Delivery
    • Setup
    • Site Settings
  • SecureClient
    • SecureClient Basics
    • System Requirements (Resources)
    • SecureClient for Windows Troubleshooting
    • Best Practice
    • iPad/Mac Changelog (Resources)
    • iPad/Mac Limitations
    • Invigilate (Surpass Platform)
    • Test Driver (Surpass Platform)
    • Admin Console
  • SecureMarker
    • Surpass SecureMarker Basics
    • Changelog (Resources)
    • Roles
    • Users
    • Site Settings
    • Examiners
    • Item Groups
    • Quality Control
    • Quotas
    • Marking
    • Escalations
    • Adjudication
    • Script Review
  • Developer
    • Surpass API v2
    • Surpass OAPI
    • SecureMarker OAPI
    • Single Sign-On
    • Scheduling System
  • Resources
    • Accessibility
    • Changelogs
    • Glossary
    • Limits
    • Release Schedule
    • Surpass Certifications
    • Surpass Learning
    • System Requirements
Suggested Search: create an item
Suggested Search: create an item

Developer Articles

APIs

  • Surpass API v2
    • API v2 Basics
      • About the Surpass API v2
      • Getting started with the Surpass API v2
      • Connecting to the Surpass API v2
      • Using the Surpass API v2 reference documentation
      • Using the Surpass API v2 test console
    • API v2 Reference
      • Item Authoring
        • BasicPage API
        • Folder API
        • Item API
        • ItemList API
        • ItemSet API
        • ItemSetLanguageVariant API
        • ItemTagValue API
        • LanguageVariant API
        • Media API
        • MediaGroup API
      • Tasks
        • Task API
        • TaskAttachment API
      • Test Creation
        • Test API
        • TestForm API
        • TestProfile API
      • Test Administration
        • Result API
        • SummaryResult API
        • TestSchedule API
        • TestSession API
        • CandidateReview API
      • Reporting
        • AnalyticsResult API
        • AnalyticsScaleScoreMapping API
        • CustomReport API
        • CustomReportGeneration API
        • Report API
        • HistoricalResult API
        • RescoringRule API
        • ScaleScoreMapping API
      • Setup
        • Candidate API
        • Centre API
        • CentreSubjectAssociation API
        • Country API
        • County API
        • ItemExposure API
        • Permission API
        • Subject API
        • TagCategory API
        • TagCollectionGroup API
        • TagGroup API
        • TagHierarchy API
        • TagValue API
        • User API
        • UserPermission API
        • WorkflowStatus API
      • Misc.
        • Token API
  • Surpass OAPI
    • OAPI Basics
      • About the Surpass OAPI
      • Getting started with the Surpass OAPI
      • Connecting to the Surpass OAPI
      • Using the Surpass OAPI Swagger console
    • OAPI Reference
      • Item Authoring
        • Item OAPI
        • ItemMetadata OAPI
        • ItemSet OAPI
      • Reporting
        • AnalyticsResult OAPI
      • Setup
        • TagCollection OAPI
        • TagCollectionGroup OAPI
        • TagGroup OAPI
        • TagValue OAPI
        • TagValueItem OAPI
      • Misc.
        • Settings OAPI
  • SecureMarker OAPI
    • OAPI Basics (SecureMarker)
      • About the SecureMarker OAPI
      • Getting started with the SecureMarker OAPI
      • Connecting to the SecureMarker OAPI
      • Using the SecureMarker OAPI Swagger console
    • OAPI Reference (SecureMarker)
      • Script Review
        • TestScript OAPI

Integrations

  • Single Sign-On
    • About Single Sign-On
    • Configuring Surpass for Single Sign-On
    • Setting up Single Sign-On IdPs
      • Setting up Single Sign-On with AD FS
      • Setting up Single Sign-On with Microsoft Entra ID
      • Setting up Single Sign-On with Okta
  • Scheduling System
    • About the scheduling system
    • Preparing to integrate with the scheduling system
    • Connecting to the scheduling system
    • Interacting with the scheduling system
      • Candidate Management
      • Staff Management
      • Scheduling Data
      • Centre Availability
      • Booking Management
Breadcrumbs Surpass OAPI > OAPI Reference > Item Authoring > ItemMetadata OAPI

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

In This Article
  • Updating an item and tag value association
  • Updating an item’s enemy relationship
  • Error Codes
  • Further reading

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.

NOTE: Requests to this endpoint ignore the Allow authors to create their own tags tag group setting to allow for a more efficient process.

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

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/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.

Request body schema

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

enemyItems array

Contains the information of any items the item set has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

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.

Further reading

Read the following articles to learn how to get started with the Surpass OAPI or more about similar APIs:

  • Getting started with the Surpass OAPI 
  • Item OAPI
  • ItemSet OAPI

About the site

The Surpass Help Site is an award-winning, comprehensive documentation resource for Surpass Assessment products.

2020 UK Technical Communication Awards Overall Winner (link opens in new tab) 2022 UK Technical Communication Awards Merit Award (link opens in new tab)

© Surpass Assessment | Terms and Policies