Skip to main content

Attributes

Attributes in Anchorpoint are custom metadata that can be attached to files, folders, and tasks to add context and organization to your assets. The Attributes API provides comprehensive functionality to read, write, and manage different types of attributes including tags, text fields, ratings, links, dates, and checkboxes.

Usage​

import apsync
import anchorpoint
from datetime import datetime

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

# Set a text attribute by name
api.attributes.set_attribute_value(ctx.path, "Description", "Hero character artwork")

# Get a text attribute
description = api.attributes.get_attribute_value(ctx.path, "Description")
print(description)  # Output: "Hero character artwork"

# Set a date attribute
api.attributes.set_attribute_value(ctx.path, "Created At", datetime.now())

# Work with attribute objects for more control
attribute = api.attributes.get_attribute("Status")
if not attribute:
    attribute = api.attributes.create_attribute("Status", apsync.AttributeType.single_choice_tag)

# Set attribute value using attribute object
api.attributes.set_attribute_value(ctx.path, attribute, "In Progress")

Attribute Types​

Anchorpoint supports several attribute types defined in the AttributeType class:

import apsync

# Available attribute types
apsync.AttributeType.single_choice_tag      # Select one tag from predefined options
apsync.AttributeType.multiple_choice_tag    # Select multiple tags from predefined options
apsync.AttributeType.text                   # Free text input
apsync.AttributeType.rating                 # Numeric rating
apsync.AttributeType.hyperlink              # URL or file path links
apsync.AttributeType.date                   # Date/timestamp values
apsync.AttributeType.checkbox               # Boolean true/false values
apsync.AttributeType.user                   # User attribute

AttributeType Class​

The AttributeType class identifies the type of an attribute.

Members​

  • single_choice_tag Select one tag from predefined options.
  • multiple_choice_tag Select multiple tags from predefined options.
  • text Free text input.
  • rating Numeric rating.
  • hyperlink URL or file path link.
  • date Date value.
  • checkbox Boolean true/false value.
  • user User attribute.

Attributes API​

The Attributes API is accessed through api.attributes and provides methods for creating, managing, and working with attributes.

import anchorpoint

api = anchorpoint.get_api()
attributes = api.attributes

Getting and Setting Attribute Values​

  • api.attributes.get_attribute_value(target, attribute) Retrieves the value of an attribute for a file, folder, or task.

    Arguments

    • target (str or class: Task): Path to the file or folder, or a Task object
    • attribute (class: Attribute or str): The attribute object or attribute name

    Returns: The attribute value, or None

  • api.attributes.set_attribute_value(target, attribute, value, update_timeline=False) Sets the value of an attribute for a file, folder, or task. Creates the attribute if it cannot be found.

    Arguments

    • target (str or class: Task): Path to the file or folder, or a Task object
    • attribute (class: Attribute or str): The attribute object or attribute name
    • value (int, str, list, class: AttributeTag, class: AttributeTagList, bool): Value to set
    • update_timeline (bool, optional): True if the timeline should be notified about the update. Default is False

Managing Attributes​

  • api.attributes.get_attribute(name, type=None) Returns an attribute by name, or None if not found.

    Arguments

    • name (str): Name of the attribute (e.g., "Status")
    • type (class: AttributeType, optional): Attribute type to filter by, or None

    Returns: class: Attribute or None

  • api.attributes.get_attribute_by_id(id) Returns an attribute with a given id.

    Arguments

    • id (str): The id of the attribute

    Returns: class: Attribute

  • api.attributes.get_attributes(type=None) Returns all attributes in the workspace or project, optionally filtered by type.

    Arguments

    • type (class: AttributeType, optional): Attribute type to filter for, or None

    Returns: list[class: Attribute]

  • api.attributes.create_attribute(name, type, tags=None, rating_max=None) Creates a new attribute in the workspace or project.

    Arguments

    • name (str): Name of the attribute (e.g., "Status")
    • type (class: AttributeType): The attribute type
    • tags (class: AttributeTagList or list, optional): List of tags to create, or None
    • rating_max (int, optional): The maximum rating value. Only valid for rating attributes

    Returns: class: Attribute

  • api.attributes.rename_attribute(attribute, name) Renames an attribute.

    Arguments

    • attribute (class: Attribute): The attribute to rename
    • name (str): The new name

Managing Tags​

  • api.attributes.set_attribute_tags(attribute, tags) Sets the available tags for a single or multiple choice tag attribute.

    Arguments

  • api.attributes.set_attribute_rating_max(attribute, max) Sets the maximum rating for a rating attribute.

    Arguments

    • attribute (class: Attribute): The attribute to update
    • max (int): The new maximum rating value

AttributeTag Class​

The AttributeTag class represents a single or multiple choice tag.

import apsync

tag = apsync.AttributeTag("In Progress", apsync.TagColor.yellow)

Constructor​

  • apsync.AttributeTag(name) Creates a new attribute tag with a default color.

    Arguments

    • name (str): Name of the tag

  • apsync.AttributeTag(name, color) Creates a new attribute tag with a specified color.

    Arguments

    • name (str): Name of the tag
    • color (class: TagColor or str): The color of the tag

Properties​

  • id (str): Unique identifier of the tag.
  • name (str): Name of the tag.
  • color (class: TagColor): The color of the tag.

Attribute Class​

The Attribute class represents an attribute definition. Attributes are not created directly — use api.attributes.get_attribute() or api.attributes.create_attribute() to obtain one.

import apsync
import anchorpoint

api = anchorpoint.get_api()
attribute = api.attributes.get_attribute("Status")
if not attribute:
    attribute = api.attributes.create_attribute("Status", apsync.AttributeType.single_choice_tag)

Properties​

  • id (str): Unique identifier for the attribute. Read-only.
  • name (str): Name of the attribute.
  • type (class: AttributeType): Type of the attribute. Read-only.
  • tags (class: AttributeTagList): Available tags for tag-type attributes.
  • rating_max (int or None): Maximum rating value. Only valid for rating attributes.

TagColor Class​

The TagColor class represents the color of a single or multiple choice tag. Use the provided class members instead of raw strings.

import apsync

color = apsync.TagColor.green

Members​

  • red Red color.
  • orange Orange color.
  • yellow Yellow color.
  • green Green color.
  • turk Turquoise color.
  • blue Blue color.
  • purple Purple color.
  • grey Grey color.

Constructor​

  • apsync.TagColor() Creates a default TagColor.

  • apsync.TagColor(color) Creates a TagColor from a string value.

    Arguments

    • color (str): Color string (e.g., "blue", "red")

AttributeTagList Class​

The AttributeTagList class is a list of AttributeTag objects. It behaves like a standard Python list.

import apsync

tags = apsync.AttributeTagList()
tags.append(apsync.AttributeTag("In Progress", apsync.TagColor.yellow))
tags.append(apsync.AttributeTag("Done", apsync.TagColor.green))

Methods​

  • append(x) Adds an item to the end of the list.

    Arguments

  • insert(i, x) Inserts an item at a given position.

    Arguments

    • i (int): The index to insert at
    • x (class: AttributeTag): The tag to insert

  • pop() Removes and returns the last item.

    Returns: class: AttributeTag

  • clear() Clears the contents.

  • extend(L) Extends the list by appending all items from another list.

    Arguments

Standalone Attribute Functions​

These are module-level functions that read and write individual attribute values directly by attribute title, without requiring an Attributes class instance.

Getting Attribute Values​

  • apsync.get_attribute_text(absolute_path, attribute_title, workspace_id=None) Retrieves the text content of an attribute for a given file or folder.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: str or None

  • apsync.get_attribute_tag(absolute_path, attribute_title, workspace_id=None) Retrieves the tag content of an attribute for a given file or folder.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: class: AttributeTag or None

  • apsync.get_attribute_tags(absolute_path, attribute_title, workspace_id=None) Retrieves the list of assigned tags of a multiple or single choice tag attribute.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: list[class: AttributeTag]

  • apsync.get_attribute_rating(absolute_path, attribute_title, workspace_id=None) Retrieves the rating content of an attribute for a given file or folder.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: int

  • apsync.get_attribute_checked(absolute_path, attribute_title, workspace_id=None) Retrieves the checkbox content of an attribute for a given file or folder.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: bool

  • apsync.get_attribute_date(absolute_path, attribute_title, workspace_id=None) Retrieves the date content of an attribute for a given file or folder. The date is in seconds since the epoch.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: int

  • apsync.get_attribute_link(absolute_path, attribute_title, workspace_id=None) Retrieves the link content of an attribute for a given file or folder.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • workspace_id (str, optional): The workspace id, or None

    Returns: str or None

Setting Attribute Values​

  • apsync.set_attribute_text(absolute_path, attribute_title, text, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the text content of an attribute for a given file or folder. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • text (str): The text to set
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_tag(absolute_path, attribute_title, tag_name, type=AttributeType.single_choice_tag, workspace_id=None, auto_create=True, tag_color=None, update_timeline=False)

    Sets the tag of an attribute for a given file or folder. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • tag_name (str): The name of the tag to set — creates a new tag if unknown
    • type (class: AttributeType, optional): The type of attribute. Default is single_choice_tag
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • tag_color (class: TagColor, optional): The color of the created tag, or None for a random color
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_tags(absolute_path, attribute_title, tag_names, type=AttributeType.multiple_choice_tag, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the tags of an attribute for a given file or folder, overwriting any existing tags. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • tag_names (list[str]): The tags to set, identified by name
    • type (class: AttributeType, optional): Must be multiple_choice_tag or single_choice_tag. Default is multiple_choice_tag
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_rating(absolute_path, attribute_title, rating, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the rating content of an attribute for a given file or folder. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • rating (int): The rating to set
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_checked(absolute_path, attribute_title, checked, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the checkbox content of an attribute for a given file or folder. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • checked (bool): Check or uncheck the attribute
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_date(absolute_path, attribute_title, secs_since_epoch, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the date content of an attribute for a given file or folder. The date is in seconds since the epoch. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • secs_since_epoch (int): The date to set in seconds since the epoch
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.set_attribute_link(absolute_path, attribute_title, link, workspace_id=None, auto_create=True, update_timeline=False)

    Sets the link content of an attribute for a given file or folder. A link can point to a website or a file or folder. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • link (str): The link to set
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

Tag Helpers​

  • apsync.add_attribute_tag(absolute_path, attribute_title, tag_name, type=AttributeType.multiple_choice_tag, workspace_id=None, auto_create=True, tag_color=None, update_timeline=False)

    Adds a tag identified by name to an attribute. If no tags are assigned yet, this is equivalent to set_attribute_tag. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • tag_name (str): The tag to add, identified by name
    • type (class: AttributeType, optional): Must be multiple_choice_tag or single_choice_tag. Default is multiple_choice_tag
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • tag_color (class: TagColor, optional): The color of the created tag, or None
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.add_attribute_tags(absolute_path, attribute_title, tag_names, type=AttributeType.multiple_choice_tag, workspace_id=None, auto_create=True, update_timeline=False)

    Adds a list of tags identified by name to an attribute. If no tags are assigned yet, this is equivalent to set_attribute_tags. Creates the attribute if it cannot be found and auto_create is True.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • tag_names (list[str]): The tags to add, identified by name
    • type (class: AttributeType, optional): Must be multiple_choice_tag or single_choice_tag. Default is multiple_choice_tag
    • workspace_id (str, optional): The workspace id, or None
    • auto_create (bool, optional): Automatically create the attribute if it does not exist. Default is True
    • update_timeline (bool, optional): True if the timeline should be notified. Default is False

  • apsync.remove_attribute_tag(absolute_path, attribute_title, tag_name, type=AttributeType.multiple_choice_tag, workspace_id=None)

    Removes a tag identified by name from an attribute.

    Arguments

    • absolute_path (str): Path to the file or folder
    • attribute_title (str): Title of the attribute
    • tag_name (str): The tag to remove, identified by name
    • type (class: AttributeType, optional): Must be multiple_choice_tag or single_choice_tag. Default is multiple_choice_tag
    • workspace_id (str, optional): The workspace id, or None

Examples​

Basic Text Attributes​

import apsync
import anchorpoint

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

# Set a text attribute by name (will auto-create if doesn't exist)
api.attributes.set_attribute_value(ctx.path, "Description", "Hero character concept art for level 1")

# Get the description
description = api.attributes.get_attribute_value(ctx.path, "Description")
print(f"Description: {description}")

Sets a text attribute by name on the current file and reads it back. If the attribute does not exist yet, it is created automatically.

Working with Tags​

import apsync
import anchorpoint

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

# Create or get a single choice tag attribute
status_attribute = api.attributes.get_attribute("Status")
if not status_attribute:
    status_attribute = api.attributes.create_attribute("Status", apsync.AttributeType.single_choice_tag)
    
    # Set up the available tags for this attribute
    tags = [
        apsync.AttributeTag("In Progress", "blue"),
        apsync.AttributeTag("Complete", "green"),
        apsync.AttributeTag("On Hold", "orange")
    ]
    api.attributes.set_attribute_tags(status_attribute, tags)

# Set the status value
api.attributes.set_attribute_value(ctx.path, status_attribute, "In Progress")

# Or set using attribute name (simpler for existing attributes)
api.attributes.set_attribute_value(ctx.path, "Status", "Complete")

# Get the current status
current_status = api.attributes.get_attribute_value(ctx.path, "Status")
print(f"Current status: {current_status}")

Creates a single-choice tag attribute called "Status" with three predefined options, sets a value on the current file, and reads it back.

Rating and Review Workflow​

import apsync
import anchorpoint
from datetime import datetime

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

# Set quality rating (1-5 stars)
api.attributes.set_attribute_value(ctx.path, "Quality", 4)

# Mark as reviewed
api.attributes.set_attribute_value(ctx.path, "Reviewed", True)

# Set review date to current time
api.attributes.set_attribute_value(ctx.path, "Review Date", datetime.now())

# Add reviewer link
api.attributes.set_attribute_value(ctx.path, "Reviewer Profile", "https://company.com/profiles/john.doe")

# Get review information
rating = api.attributes.get_attribute_value(ctx.path, "Quality")
is_reviewed = api.attributes.get_attribute_value(ctx.path, "Reviewed")
review_date = api.attributes.get_attribute_value(ctx.path, "Review Date")

print(f"Rating: {rating}/5 stars")
print(f"Reviewed: {is_reviewed}")
print(f"Review date: {review_date}")

Demonstrates setting multiple attribute types on a single file — a numeric rating, a checkbox, a date, and a hyperlink — then reads them all back.

Batch Processing with Attributes​

import apsync
import anchorpoint
import os
from datetime import datetime

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

# Process all selected files
for file_path in ctx.selected_files:
    filename = os.path.basename(file_path)
    
    # Set common attributes based on file type
    if filename.lower().endswith(('.jpg', '.png', '.tiff')):
        api.attributes.set_attribute_value(file_path, "Type", "Image")
        api.attributes.set_attribute_value(file_path, "Format", "Raster")
    elif filename.lower().endswith(('.fbx', '.obj', '.blend')):
        api.attributes.set_attribute_value(file_path, "Type", "3D Model")
        api.attributes.set_attribute_value(file_path, "Format", "3D Mesh")
    
    # Set processing timestamp
    api.attributes.set_attribute_value(file_path, "Processed", datetime.now())
    
    print(f"Processed: {filename}")

Iterates over all selected files and sets "Type" and "Format" attributes based on the file extension, tagging images and 3D models differently.

Creating Complex Attribute Workflows​

import apsync
import anchorpoint

ctx = anchorpoint.get_context()
api = anchorpoint.get_api()

def create_attribute_example():
    # This example shows how to access attributes and update the set of tags
    attribute = api.attributes.get_attribute("Python Example")
    if not attribute:
        attribute = api.attributes.create_attribute(
            "Python Example", apsync.AttributeType.single_choice_tag
        )

    new_tag_name = f"Example Tag {len(attribute.tags) + 1}"
    tags = attribute.tags
    tags.append(apsync.AttributeTag(new_tag_name, "blue"))
    api.attributes.set_attribute_tags(attribute, tags)

    return attribute

def set_attributes(file_path, example_attribute):
    # We can either use the attribute that we have created before ...
    latest_tag = example_attribute.tags[-1]
    api.attributes.set_attribute_value(file_path, example_attribute, latest_tag)
    print(api.attributes.get_attribute_value(file_path, example_attribute))

    # ... or create / use attributes described by their title
    api.attributes.set_attribute_value(file_path, "Message", "Hello from Python")
    print(api.attributes.get_attribute_value(file_path, "Message"))

    # To set a date, use datetime.datetime or a unix timestamp
    from datetime import datetime
    api.attributes.set_attribute_value(file_path, "Created At", datetime.now())

# Create the example attribute
attribute = create_attribute_example()

# Apply to all selected files
for file_path in ctx.selected_files:
    set_attributes(file_path, attribute)

Shows a reusable pattern for managing a tag attribute: creates the attribute if it doesn't exist, appends a new tag to its list, then applies both a tag value and a text value to every selected file.