Skip to main content

Tags

Tags are labels that help organize nodes and files. They enable filtering, categorization, and fine-grained access control through exposure profiles.

What is a Tag?​

Tags are simple labels with:

  • A name (e.g., "Work", "Personal", "Important")
  • An optional color for visual distinction
  • A unique ID for programmatic access

Tag Structure​

{
  "id": "tag_work123",
  "name": "Work",
  "color": "#4A90D9",
  "owner_id": "user_123",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Working with Tags​

Create a Tag​

tag = client.tags.create(
    user_id="user-123",
    name="Important",
    color="#EF4444"  # Red
)
print(f"Created tag: {tag['id']}")

List Tags​

result = client.tags.list(user_id="user-123")

for tag in result['items']:
    print(f"[{tag['color']}] {tag['name']}")

Update a Tag​

updated = client.tags.update(
    user_id="user-123",
    tag_id="tag_work123",
    name="Work Projects",
    color="#3B82F6"
)

Delete a Tag​

# This removes the tag but doesn't delete nodes with this tag
client.tags.delete(user_id="user-123", tag_id="tag_work123")

Tagging Nodes​

Add Tag to Node​

# Add a tag
client.nodes.add_tag(
    user_id="user-123",
    node_id="node_abc",
    tag_id="tag_work"
)

Remove Tag from Node​

# Remove a tag
client.nodes.remove_tag(
    user_id="user-123",
    node_id="node_abc",
    tag_id="tag_work"
)

Create Node with Tags​

node = client.nodes.create(
    user_id="user-123",
    title="Meeting Notes",
    value="...",
    node_type="note",
    tag_ids=["tag_work", "tag_meetings"]
)

Querying by Tags​

Get All Nodes with a Tag​

# Get all nodes tagged "work"
result = client.tags.get_nodes(
    user_id="user-123",
    tag_id="tag_work"
)

print(f"Found {result['total']} work-related nodes")

Filter Nodes by Multiple Tags​

# Get nodes that have BOTH tags
result = client.nodes.list(
    user_id="user-123",
    tag_ids=["tag_work", "tag_important"]
)

Get Files with a Tag​

result = client.tags.get_files(
    user_id="user-123",
    tag_id="tag_documents"
)

for file in result['items']:
    print(f"📄 {file['filename']}")

Tags and Access Control​

Tags are central to Exposure Profiles. Users can:

  • Share only nodes with specific tags
  • Exclude nodes with certain tags from sharing

Example exposure profile:

{
  "name": "Work Only",
  "scope": {
    "tag_ids": ["tag_work", "tag_projects"],
    "exclude_tag_ids": ["tag_private", "tag_personal"]
  }
}

This shares only work-related data while keeping personal items private.

Color Conventions​

Use colors consistently to help users visually identify tag categories:

CategorySuggested ColorHex
WorkBlue#3B82F6
PersonalGreen#22C55E
ImportantRed#EF4444
ArchiveGray#6B7280
FamilyPurple#8B5CF6
HealthTeal#14B8A6

Best Practices​

1. Keep Tag Names Short and Clear​

# Good
"Work", "Personal", "Urgent", "Archive"

# Bad
"Work-related items and documents", "Personal stuff"

2. Use a Consistent Vocabulary​

Define your app's tag vocabulary:

SUGGESTED_TAGS = [
    {"name": "Work", "color": "#3B82F6"},
    {"name": "Personal", "color": "#22C55E"},
    {"name": "Important", "color": "#EF4444"},
    {"name": "Archive", "color": "#6B7280"},
]

3. Let Users Create Their Own Tags​

Don't force a rigid taxonomy. Users have unique organizational styles:

# Check if tag exists, create if not
existing_tags = client.tags.list(user_id=user_id, search="my-custom-tag")
if not existing_tags['items']:
    tag = client.tags.create(user_id=user_id, name="my-custom-tag")

4. Use Tags for Privacy Boundaries​

Encourage users to tag sensitive data:

# Create privacy-related tags
client.tags.create(user_id=user_id, name="Private", color="#EF4444")
client.tags.create(user_id=user_id, name="Sensitive", color="#F59E0B")

Then use exposure profiles to exclude these from sharing.

Next Steps​