# Tags

Browse the tag vocabulary and find records carrying an exact tag.

Canonical HTML: https://developer.shelfcycle.com/guides/tags

Browse the organization's tag vocabulary, then find the customers, suppliers, products, or product families carrying one exact tag.

Use Tags when a connected workflow starts from a shared business grouping such as preferred suppliers, strategic customers, or a product collection. Use [Entity Resolution](/guides/entity-resolution) when the next step is choosing one exact record ID from business wording.

## Access

Both routes require `tags:read` plus the acting user's current Tags access. Finding tagged records also requires current access to the requested entity type.

`GET /me` reports `effectiveCapabilities.tags.vocabulary` and the available classes in `effectiveCapabilities.tags.viewableEntityTypes`.

## Browse the tag vocabulary

```text
GET /tags
```

Optional query parameters:

| Parameter | Use it for |
| --- | --- |
| `entityType` | Tags that apply to `customer`, `supplier`, `product`, or `product_family`. |
| `limit` | Rows per page from 1 to 100. The default is 25. |
| `cursor` | The continuation value returned by the preceding page. |

```bash
curl "$SHELFCYCLE_API_BASE_URL/tags?entityType=product&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Product collection sync"
```

```json
{
  "data": [
    {
      "id": "tag-id",
      "label": "Sustainable Solvents",
      "description": "Products in the sustainable solvents collection",
      "applicableEntityTypes": ["product", "product_family"]
    }
  ],
  "meta": {
    "capabilityKey": "list_tags",
    "capabilityVersion": "1.1.0",
    "returnedRecords": 1,
    "populationCount": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "label_id",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id"
  }
}
```

Each tag includes a stable `id`, its complete `label`, an optional `description`, and every supported entity type it can organize.

## Find records carrying a tag

```text
GET /tagged-records
```

Every request needs one `entityType` and exactly one case-sensitive tag selector:

- `tagId` uses the stable ID from `GET /tags`.
- `label` uses the exact tag label.

Optional `nameQuery` narrows the selected records by name. `includeArchived=true` includes archived records. `limit` and `cursor` control continuation.

```bash
curl "$SHELFCYCLE_API_BASE_URL/tagged-records?tagId=tag-id&entityType=product&nameQuery=acetone&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Product collection sync"
```

```json
{
  "data": {
    "resolvedTag": {
      "id": "tag-id",
      "label": "Sustainable Solvents",
      "description": "Products in the sustainable solvents collection"
    },
    "records": [
      {
        "entityType": "product",
        "id": "product-id",
        "displayName": "ACETONE-PAIL",
        "externalId": "SOLVENT-1042",
        "archived": false
      }
    ]
  },
  "meta": {
    "capabilityKey": "find_tagged_records",
    "capabilityVersion": "1.1.0",
    "returnedRecords": 1,
    "populationCount": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "display_name_id",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id",
    "archivedExcluded": true
  }
}
```

`resolvedTag` confirms the exact grouping used. Each record provides the identity needed for a follow-up detail read, Entity Resolution comparison, report, or readiness check.

## Continue larger results

When `meta.hasMore` is true, repeat the original filters and `limit`, then add `meta.nextCursor`:

```bash
curl "$SHELFCYCLE_API_BASE_URL/tagged-records?tagId=tag-id&entityType=product&nameQuery=acetone&limit=25&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

The cursor stays with the original endpoint, filters, page size, organization, and key. `populationCount` becomes available when the final page completes the current result set. Restart from the original filters when refreshing the directory.

## Pair Tags with Entity Resolution

Tags answer which authorized records carry one exact business grouping. Entity Resolution answers which single ID best matches familiar wording.

When both `search:read` and `tags:read` are available, Entity Resolution can include `relatedTags` for the requested class. Each entry includes the tag label, description, and matching classes. Use that context to understand a candidate, then use `GET /tagged-records` when the workflow needs the complete authorized group.