API Reference

REST API

Version 2.0

Replace Marking

PUT/api/v2/admin/markings/{markingId}

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Replace the Marking with the specified id.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:admin-write.

Path parameters

markingId

string

The ID of a security marking.

Query parameters

preview

boolean

optional

Enables the use of preview functionality.

Request body

ReplaceMarkingRequest

object

Hide child attributes

name

string

description

string

optional

Response body

Marking

object

The replaced Marking

Hide child attributes

string

The ID of a security marking.

categoryId

string

The ID of a marking category. For user-created categories, this will be a UUID. Markings associated with Organizations are placed in a category with ID "Organization".

name

string

description

string

optional

organization

string

optional

If this marking is associated with an Organization, its RID will be populated here.

createdTime

string

The time at which the resource was created.

createdBy

string

optional

The Foundry user who created this resource

Examples

Request

Copied!

curl -X PUT \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/admin/markings/18212f9a-0e63-4b79-96a0-aae04df23336?preview=true" \
	-d '{"name":"PII","description":"Contains personally identifiable information about our customers"}'

Response

Copied!

{
  "createdBy": "f05f8da4-b84c-4fca-9c77-8af0b13d11de",
  "organization": "ri.multipass..organization.c30ee6ad-b5e4-4afe-a74f-fe4a289f2faa",
  "name": "PII",
  "description": "Contains personally identifiable information about our customers",
  "createdTime": "2003-05-06T12:34:56.789Z",
  "id": "18212f9a-0e63-4b79-96a0-aae04df23336",
  "categoryId": "0950264e-01c8-4e83-81a9-1a6b7f77621a"
}

Error responses

Error Name
`GetMarkingCategoryPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	The provided token does not have permission to view the marking category.
	Parameters	`markingCategoryId`
`MarkingNameInCategoryAlreadyExists`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	A marking with the same name already exists in the category.
	Parameters	`displayName, categoryId`
`GetMarkingPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	The provided token does not have permission to view the marking.
	Parameters	`markingId`
`MarkingNameIsEmpty`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The marking name is empty.
	Parameters
`ReplaceMarkingPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	Could not replace the Marking.
	Parameters	`markingId`
`MarkingNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The given Marking could not be found.
	Parameters	`markingId`

See Errors for a general overview of errors in the platform.