Docs/Guides/Organising with Tags

Organising instruments with tags

This guide shows how to build a tag hierarchy, assign tags to instruments in bulk, and query instruments by their position in the tag tree. Tags are a powerful alternative to rigid type schemas for multi-dimensional classification.

Designing your tag hierarchy

Tags are most useful when they represent orthogonal dimensions of classification that cut across instrument types. Good examples:

By geography

#aus → #aus#asx, #aus#chi-x #us → #us#nyse, #us#nasdaq

By asset class

#equity → #equity#large-cap, #equity#small-cap #fixed-income → #fixed-income#sovereign

Unlike instrument types (which define schema), tags can be assigned freely across any combination of instruments regardless of their type.

Creating the tag tree

Create parent tags first, then child tags referencing their parent by UUID or slug:

# Create root tag
curl -X POST .../instrument-tags \
  -d '{"name": "Australian Equities", "slug": "aus-eq"}'

# Create child tag (reference parent by slug)
curl -X POST .../instrument-tags \
  -d '{"name": "ASX Large Cap", "slug": "asx-lc", "parent_id": "aus-eq"}'

Bulk-assigning tags during import

When creating instruments, you can’t assign tags in the same request — tags must be assigned after creation. Use the bulk replace endpoint to set all tags at once:

for row in csv_rows:
  # Create instrument
  inst = client.post("/instruments", json={
    "name": row["name"],
    "identifier": row["ticker"],
    "type_id": "equity"
  }).json()
  
  # Assign tags in bulk
  tags = ["aus-eq"]
  if row["market_cap"] > "10000000000":
    tags.append("#aus-eq#asx-lc")
  client.put(
    f"/instruments/{inst['id']}/tags",
    json=tags
  )

Use PUT /instruments/{id}/tags (bulk replace) rather than calling POST for each tag individually. One request sets all tags atomically.

Querying instruments by tag

Use tagged_with_descendants to find all instruments anywhere under a tag node:

All Australian equities (including sub-tags)

POST /instruments/filter

{
  "filter": {
    "and": [
      { "field": "tags", "op": "tagged_with_descendants", "value": "#aus-eq" }
    ]
  }
}

Use tagged (without descendants) to match only instruments tagged with the exact tag — useful when you want only the instruments directly in a category, not subcategories:

Only ASX Large Cap (exact match)

{ "field": "tags", "op": "tagged", "value": "#aus-eq#asx-lc" }

Renaming and reorganising tags

Tags can be renamed, re-slugged, or re-parented without affecting existing assignments. Re-parenting moves the tag and its entire subtree to a new location in the hierarchy.

Move a tag to a new parent

PATCH /instrument-tags/asx-lc

{
  "parent_id": "global-eq"
}

Circular references are rejected — you cannot make a tag its own ancestor. The API returns 409 Conflict if the re-parent operation would create a cycle.