# Marking service

This service manages Markings, which are a mechanism to restrict access to data sources.

OpenAPI file: [`nominal.authorization.markings.v1.json`](https://dev.nominal.io/api/_downloads/66125d2cc76551a5ba9b2c53a3be97a3/nominal.authorization.markings.v1.json)

## Endpoints

### Create marking

POST `/authorization/markings/v1`

Creates a marking. Throws HTTP 409 / gRPC 6 if a marking with the same ID already exists. Throws HTTP 403 / gRPC 7 if the user does not have permission to create a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read some of the specified groups.

Body

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   ​

    Fields of `Symbol`

    one of `icon`, `emoji`, `image` required
    :   ​

        **icon**

        `icon` string
        :   Icon name (e.g. castle)

        **emoji**

        `emoji` string
        :   Emoji name (e.g. :castle:)

        **image**

        `image` string
        :   Image url (e.g. https://example.com/image.png)

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

    Fields of `Color`

    `hexCode` string
    :   hex color Matches `^#[0-9a-f]{6}$`.

Response

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

    Fields of `Symbol`

    one of `icon`, `emoji`, `image`
    :   ​

        **icon**

        `icon` string
        :   Icon name (e.g. castle)

        **emoji**

        `emoji` string
        :   Emoji name (e.g. :castle:)

        **image**

        `image` string
        :   Image url (e.g. https://example.com/image.png)

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

    Fields of `Color`

    `hexCode` string
    :   hex color Matches `^#[0-9a-f]{6}$`.

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  }
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"icon": "<icon>"},
        "color": {"hexCode": "<hex code>"},
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"icon": "<icon>"},
        "color": {"hexCode": "<hex code>"},
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "id": "<id>",
                "description": "<description>",
                "authorizedGroups": {"groupRids": ["<group rids>"]},
                "symbol": {"icon": "<icon>"},
                "color": {"hexCode": "<hex code>"},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}
```

### Archive markings

POST `/authorization/markings/v1/archive-batch`

Archives markings. Archiving a marking is an idempotent operation that prevents further changes or applications of the marking. Archived markings will not appear in search but can be retrieved by `get` endpoints. Throws HTTP 403 / gRPC 7 if the user does not have permission to archive one or more of the markings or if any of the markings are not found. Throws HTTP 400 / gRPC 3 if the archived marking is currently applied to one or more resources.

Body

The body is an array of string.

Response

An empty JSON object, `{}`.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "string"
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/archive-batch",
            headers={"Authorization": "Bearer <api key>"},
            json=["string"],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{}
```

### Get authorized groups by marking

POST `/authorization/markings/v1/authorized-groups-by-marking`

Gets the authorized Groups for each of a set of Markings. Markings that are not found or for which the user does not have permission to read will be filtered from the response. Groups for which the user does not have permission to read will be filtered from the response.

Body

`markingRids` array of string
:   ​

Response

`authorizedGroupsByMarking` map of string to [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   ​

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/authorized-groups-by-marking",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "authorizedGroupsByMarking": {
    "<key>": {
      "groupRids": [
        "<group rids>"
      ]
    }
  }
}
```

### Batch get markings

POST `/authorization/markings/v1/batch-get`

Gets multiple markings by RID. If a marking is not found or the user doesn’t have permission to read it, it will not be included in the response.

Body

`markingRids` array of string
:   ​

Response

`markings` array of [`Marking`](https://dev.nominal.io/api/rest/marking-service.md#marking)
:   ​

    Fields of `Marking`

    `rid` string
    :   ​

    `id` string
    :   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

    `description` string
    :   ​

    `authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
    :   Group RIDs that are authorized to access data sources with this marking.

        Fields of `AuthorizedGroups`

        `groupRids` array of string
        :   ​

    `symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
    :   Symbol and color to identify markings

        Fields of `Symbol`

        one of `icon`, `emoji`, `image`
        :   ​

            **icon**

            `icon` string
            :   Icon name (e.g. castle)

            **emoji**

            `emoji` string
            :   Emoji name (e.g. :castle:)

            **image**

            `image` string
            :   Image url (e.g. https://example.com/image.png)

    `color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
    :   ​

        Fields of `Color`

        `hexCode` string
        :   hex color Matches `^#[0-9a-f]{6}$`.

    `createdAt` string (date-time)
    :   ​

    `updatedAt` string (date-time)
    :   ​

    `isArchived` boolean
    :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "markings": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "authorizedGroups": {
        "groupRids": [
          "<group rids>"
        ]
      },
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ]
}
```

### Batch get marking metadata

POST `/authorization/markings/v1/batch-get-metadata`

Gets metadata for multiple markings by RID. Metadata does not include the authorized groups. If a marking is not found or the user doesn’t have permission to read it, it will not be included in the response.

Body

`markingRids` array of string
:   ​

Response

`markingMetadatas` array of [`MarkingMetadata`](https://dev.nominal.io/api/rest/marking-service.md#markingmetadata)
:   ​

    Fields of `MarkingMetadata`

    `rid` string
    :   ​

    `id` string
    :   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

    `description` string
    :   ​

    `symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
    :   Symbol and color to identify markings

        Fields of `Symbol`

        one of `icon`, `emoji`, `image`
        :   ​

            **icon**

            `icon` string
            :   Icon name (e.g. castle)

            **emoji**

            `emoji` string
            :   Emoji name (e.g. :castle:)

            **image**

            `image` string
            :   Image url (e.g. https://example.com/image.png)

    `color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
    :   ​

        Fields of `Color`

        `hexCode` string
        :   hex color Matches `^#[0-9a-f]{6}$`.

    `createdAt` string (date-time)
    :   ​

    `updatedAt` string (date-time)
    :   ​

    `isArchived` boolean
    :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingRids": [
    "<marking rids>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={"markingRids": ["<marking rids>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/batch-get-metadata",
            headers={"Authorization": "Bearer <api key>"},
            json={"markingRids": ["<marking rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "markingMetadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ]
}
```

### Get marking by ID

GET `/authorization/markings/v1/id/{id}`

Gets a marking by its ID, a human-readable identifier unique within the org. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found.

Path parameters

`id` string required
:   Matches `^[a-z][a-z0-9-]*$`.

Response

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

    Fields of `Symbol`

    one of `icon`, `emoji`, `image`
    :   ​

        **icon**

        `icon` string
        :   Icon name (e.g. castle)

        **emoji**

        `emoji` string
        :   Emoji name (e.g. :castle:)

        **image**

        `image` string
        :   Image url (e.g. https://example.com/image.png)

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

    Fields of `Color`

    `hexCode` string
    :   hex color Matches `^#[0-9a-f]{6}$`.

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/authorization/markings/v1/id/<id>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}
```

### Get markings for resources

POST `/authorization/markings/v1/markings-for-resources`

Gets the requested resources and the markings applied to them. Since the number of markings applied to a resource is typically small, this endpoint will return all markings for each resource. Any unauthorized resources or markings will be filtered from the response.

Body

`resources` array of string
:   The resources to get the markings for.

Response

`resourceToMarkings` map of string to [`ResourceMarkingsList`](https://dev.nominal.io/api/rest/marking-service.md#resourcemarkingslist)
:   A map from resource ID to the markings applied to them.

    Fields of `ResourceMarkingsList`

    `appliedMarkings` array of [`AppliedMarking`](https://dev.nominal.io/api/rest/marking-service.md#appliedmarking)
    :   ​

        Fields of `AppliedMarking`

        `markingRid` string
        :   ​

        `appliedAt` string (date-time)
        :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resources": [
    "<resources>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"resources": ["<resources>"]},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/markings-for-resources",
            headers={"Authorization": "Bearer <api key>"},
            json={"resources": ["<resources>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "resourceToMarkings": {
    "<key>": {
      "appliedMarkings": [
        {
          "markingRid": "<marking rid>",
          "appliedAt": "2026-01-01T00:00:00Z"
        }
      ]
    }
  }
}
```

### Update markings on resource

POST `/authorization/markings/v1/resource/{resource}/markings`

Update the markings that are applied on a resource. Supports applying and removing markings at once. This endpoint can be used to atomically replace the markings on a resource, or bulk apply/remove markings. This operation is idempotent and will not throw an error if the marking is already applied/removed on the resource. If a resource marking pair is present in both `markings_to_apply` and `markings_to_remove`, this will throw. Throws HTTP 403 / gRPC 7 if the user does not have permission to change the markings on the resource. Throws HTTP 400 / gRPC 3 if trying to apply an archived marking.

Path parameters

`resource` string required
:   ​

Body

`markingsToApply` array of string
:   ​

`markingsToRemove` array of string
:   ​

Response

An empty JSON object, `{}`.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "markingsToApply": [
    "<markings to apply>"
  ],
  "markingsToRemove": [
    "<markings to remove>"
  ]
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "markingsToApply": ["<markings to apply>"],
        "markingsToRemove": ["<markings to remove>"],
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "markingsToApply": ["<markings to apply>"],
        "markingsToRemove": ["<markings to remove>"],
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/resource/<resource>/markings",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "markingsToApply": ["<markings to apply>"],
                "markingsToRemove": ["<markings to remove>"],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{}
```

### Search markings

POST `/authorization/markings/v1/search`

Search Markings, returning paged results. Throws HTTP 400 / gRPC 3 if the query is incorrectly formed.

Body

`query` [`SearchMarkingsQuery`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquery)
:   ​

    Fields of `SearchMarkingsQuery`

    one of `idExactSubstringSearch`, `and`, `or` required
    :   ​

        **idExactSubstringSearch**

        `idExactSubstringSearch` string
        :   Search for markings with an ID that contains the given query as a substring.

        **and**

        `and` [`SearchMarkingsQueryList`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquerylist)
        :   ​

            Fields of `SearchMarkingsQueryList`

            `queries` array of [`SearchMarkingsQuery`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquery)
            :   ​

        **or**

        `or` [`SearchMarkingsQueryList`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquerylist)
        :   ​

`pageSize` integer
:   Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.

`nextPageToken` string
:   ​

Response

`markingMetadatas` array of [`MarkingMetadata`](https://dev.nominal.io/api/rest/marking-service.md#markingmetadata)
:   ​

    Fields of `MarkingMetadata`

    `rid` string
    :   ​

    `id` string
    :   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

    `description` string
    :   ​

    `symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
    :   Symbol and color to identify markings

        Fields of `Symbol`

        one of `icon`, `emoji`, `image`
        :   ​

            **icon**

            `icon` string
            :   Icon name (e.g. castle)

            **emoji**

            `emoji` string
            :   Emoji name (e.g. :castle:)

            **image**

            `image` string
            :   Image url (e.g. https://example.com/image.png)

    `color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
    :   ​

        Fields of `Color`

        `hexCode` string
        :   hex color Matches `^#[0-9a-f]{6}$`.

    `createdAt` string (date-time)
    :   ​

    `updatedAt` string (date-time)
    :   ​

    `isArchived` boolean
    :   ​

`nextPageToken` string
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "query": {
    "idExactSubstringSearch": "<id exact substring search>"
  },
  "pageSize": 1,
  "nextPageToken": "<next page token>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"idExactSubstringSearch": "<id exact substring search>"},
        "pageSize": 1,
        "nextPageToken": "<next page token>",
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "query": {"idExactSubstringSearch": "<id exact substring search>"},
        "pageSize": 1,
        "nextPageToken": "<next page token>",
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "query": {"idExactSubstringSearch": "<id exact substring search>"},
                "pageSize": 1,
                "nextPageToken": "<next page token>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "markingMetadatas": [
    {
      "rid": "<rid>",
      "id": "<id>",
      "description": "<description>",
      "symbol": {
        "icon": "<icon>"
      },
      "color": {
        "hexCode": "<hex code>"
      },
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "isArchived": true
    }
  ],
  "nextPageToken": "<next page token>"
}
```

### Unarchive markings

POST `/authorization/markings/v1/unarchive-batch`

Unarchives markings. Restores ability to apply and modify marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to unarchive one or more of the markings or if any of the markings are not found.

Body

The body is an array of string.

Response

An empty JSON object, `{}`.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "string"
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
    headers={"Authorization": "Bearer <api key>"},
    json=["string"],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/unarchive-batch",
            headers={"Authorization": "Bearer <api key>"},
            json=["string"],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{}
```

### Get resources for marking

POST `/authorization/markings/v1/{markingRid}/resources`

Gets the resources that a Marking is applied to. This endpoint is paginated. Any unauthorized resources will be filtered from the response. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking.

Path parameters

`markingRid` string required
:   ​

Body

`pageSize` integer
:   Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.

`nextPageToken` string
:   ​

Response

`resources` array of [`MarkedResource`](https://dev.nominal.io/api/rest/marking-service.md#markedresource)
:   ​

    Fields of `MarkedResource`

    `resource` string
    :   ​

    `appliedAt` string (date-time)
    :   ​

`nextPageToken` string
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "pageSize": 1,
  "nextPageToken": "<next page token>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"pageSize": 1, "nextPageToken": "<next page token>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
    headers={"Authorization": "Bearer <api key>"},
    json={"pageSize": 1, "nextPageToken": "<next page token>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/authorization/markings/v1/<marking rid>/resources",
            headers={"Authorization": "Bearer <api key>"},
            json={"pageSize": 1, "nextPageToken": "<next page token>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "resources": [
    {
      "resource": "<resource>",
      "appliedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "<next page token>"
}
```

### Get marking

GET `/authorization/markings/v1/{rid}`

Gets a marking by its RID. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found.

Path parameters

`rid` string required
:   ​

Response

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

    Fields of `Symbol`

    one of `icon`, `emoji`, `image`
    :   ​

        **icon**

        `icon` string
        :   Icon name (e.g. castle)

        **emoji**

        `emoji` string
        :   Emoji name (e.g. :castle:)

        **image**

        `image` string
        :   Image url (e.g. https://example.com/image.png)

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

    Fields of `Color`

    `hexCode` string
    :   hex color Matches `^#[0-9a-f]{6}$`.

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}
```

### Update marking

PUT `/authorization/markings/v1/{rid}`

Updates a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to update the marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read any of the specified groups. Throws HTTP 403 / gRPC 5 if the marking is not found. Throws HTTP 409 / gRPC 6 if trying to update the ID of a marking to an ID that already exists. Throws HTTP 400 / gRPC 3 if trying to update an archived marking.

Path parameters

`rid` string required
:   ​

Body

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`UpdateMarkingSymbolWrapper`](https://dev.nominal.io/api/rest/marking-service.md#updatemarkingsymbolwrapper)
:   ​

    Fields of `UpdateMarkingSymbolWrapper`

    `value` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
    :   ​

        Fields of `Symbol`

        one of `icon`, `emoji`, `image` required
        :   ​

            **icon**

            `icon` string
            :   Icon name (e.g. castle)

            **emoji**

            `emoji` string
            :   Emoji name (e.g. :castle:)

            **image**

            `image` string
            :   Image url (e.g. https://example.com/image.png)

`color` [`UpdateMarkingColorWrapper`](https://dev.nominal.io/api/rest/marking-service.md#updatemarkingcolorwrapper)
:   ​

    Fields of `UpdateMarkingColorWrapper`

    `value` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
    :   ​

        Fields of `Color`

        `hexCode` string
        :   hex color Matches `^#[0-9a-f]{6}$`.

Response

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

    Fields of `AuthorizedGroups`

    `groupRids` array of string
    :   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

    Fields of `Symbol`

    one of `icon`, `emoji`, `image`
    :   ​

        **icon**

        `icon` string
        :   Icon name (e.g. castle)

        **emoji**

        `emoji` string
        :   Emoji name (e.g. :castle:)

        **image**

        `image` string
        :   Image url (e.g. https://example.com/image.png)

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

    Fields of `Color`

    `hexCode` string
    :   hex color Matches `^#[0-9a-f]{6}$`.

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "value": {
      "icon": "<icon>"
    }
  },
  "color": {
    "value": {
      "hexCode": "<hex code>"
    }
  }
}'
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"value": {"icon": "<icon>"}},
        "color": {"value": {"hexCode": "<hex code>"}},
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {"groupRids": ["<group rids>"]},
        "symbol": {"value": {"icon": "<icon>"}},
        "color": {"value": {"hexCode": "<hex code>"}},
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/authorization/markings/v1/<rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "id": "<id>",
                "description": "<description>",
                "authorizedGroups": {"groupRids": ["<group rids>"]},
                "symbol": {"value": {"icon": "<icon>"}},
                "color": {"value": {"hexCode": "<hex code>"}},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<rid>",
  "id": "<id>",
  "description": "<description>",
  "authorizedGroups": {
    "groupRids": [
      "<group rids>"
    ]
  },
  "symbol": {
    "icon": "<icon>"
  },
  "color": {
    "hexCode": "<hex code>"
  },
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "isArchived": true
}
```

## Types

### AppliedMarking

`markingRid` string
:   ​

`appliedAt` string (date-time)
:   ​

### AuthorizedGroups

`groupRids` array of string
:   ​

### Color

`hexCode` string
:   hex color Matches `^#[0-9a-f]{6}$`.

### MarkedResource

`resource` string
:   ​

`appliedAt` string (date-time)
:   ​

### Marking

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`authorizedGroups` [`AuthorizedGroups`](https://dev.nominal.io/api/rest/marking-service.md#authorizedgroups)
:   Group RIDs that are authorized to access data sources with this marking.

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

### MarkingMetadata

A leaner representation of a Marking that doesn’t include the authorized groups.

`rid` string
:   ​

`id` string
:   Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens. Matches `^[a-z][a-z0-9-]*$`.

`description` string
:   ​

`symbol` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   Symbol and color to identify markings

`color` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

`isArchived` boolean
:   ​

### ResourceMarkingsList

`appliedMarkings` array of [`AppliedMarking`](https://dev.nominal.io/api/rest/marking-service.md#appliedmarking)
:   ​

### SearchMarkingsQuery

Set exactly one of the fields below.

one of `idExactSubstringSearch`, `and`, `or` required
:   ​

    **idExactSubstringSearch**

    `idExactSubstringSearch` string
    :   Search for markings with an ID that contains the given query as a substring.

    **and**

    `and` [`SearchMarkingsQueryList`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquerylist)
    :   ​

    **or**

    `or` [`SearchMarkingsQueryList`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquerylist)
    :   ​

### SearchMarkingsQueryList

`queries` array of [`SearchMarkingsQuery`](https://dev.nominal.io/api/rest/marking-service.md#searchmarkingsquery)
:   ​

### Symbol

Set exactly one of the fields below.

one of `icon`, `emoji`, `image` required
:   ​

    **icon**

    `icon` string
    :   Icon name (e.g. castle)

    **emoji**

    `emoji` string
    :   Emoji name (e.g. :castle:)

    **image**

    `image` string
    :   Image url (e.g. https://example.com/image.png)

### UpdateMarkingColorWrapper

`value` [`Color`](https://dev.nominal.io/api/rest/marking-service.md#color)
:   ​

### UpdateMarkingSymbolWrapper

`value` [`Symbol`](https://dev.nominal.io/api/rest/marking-service.md#symbol)
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.