Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

76.5 KB
Raw Blame
{
  "openapi": "3.1.0",
  "info": {
    "title": "properties_service",
    "description": "",
    "termsOfService": "https://macro.com/terms",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {
    "/properties/definitions": {
      "get": {
        "tags": ["Properties"],
        "summary": "List property definitions with flexible filtering",
        "operationId": "list_properties",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "description": "Filter by scope: 'user', 'team', 'system', or 'all'",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyScope"
            }
          },
          {
            "name": "include_options",
            "in": "query",
            "description": "Whether to include property options in the response",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "for_entity_type",
            "in": "query",
            "description": "Filter properties applicable to a specific entity type",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/EntityType"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Properties retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PropertyDefinitionResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "tags": ["Properties"],
        "summary": "Create a new property definition",
        "operationId": "create_property_definition",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePropertyDefinitionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Property definition created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyDefinition"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Team membership required for team scope"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/definitions/{definition_id}": {
      "get": {
        "tags": ["Properties"],
        "summary": "Get a property definition by ID",
        "operationId": "get_property_definition",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Property definition retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyDefinition"
                }
              }
            }
          },
          "400": {
            "description": "Invalid property ID"
          },
          "404": {
            "description": "Property definition not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "delete": {
        "tags": ["Properties"],
        "summary": "Delete a property definition",
        "operationId": "delete_property_definition",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Property definition deleted successfully"
          },
          "400": {
            "description": "Invalid property ID"
          },
          "403": {
            "description": "Cannot modify system properties"
          },
          "404": {
            "description": "Property definition not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/definitions/{definition_id}/options": {
      "get": {
        "tags": ["Properties"],
        "summary": "Get all options for a property (for dropdowns)",
        "operationId": "get_property_options",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Property options retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PropertyOption"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Property not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "tags": ["Properties"],
        "summary": "Add a new option to a property dropdown",
        "operationId": "add_property_option",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddPropertyOptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Property option created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyOption"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Cannot modify system properties"
          },
          "404": {
            "description": "Property not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/definitions/{definition_id}/options/{option_id}": {
      "delete": {
        "tags": ["Properties"],
        "summary": "Delete a property option",
        "operationId": "delete_property_option",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "option_id",
            "in": "path",
            "description": "Property option ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Property option deleted successfully"
          },
          "400": {
            "description": "Invalid option ID"
          },
          "403": {
            "description": "Cannot modify system properties"
          },
          "404": {
            "description": "Property option not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "patch": {
        "tags": ["Properties"],
        "summary": "Update a property option in place (rename / recolor / reorder).",
        "description": "The option id is preserved, so the change is reflected on every entity that references it.",
        "operationId": "update_property_option",
        "parameters": [
          {
            "name": "definition_id",
            "in": "path",
            "description": "Property definition ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "option_id",
            "in": "path",
            "description": "Property option ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePropertyOptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Property option updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyOption"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Cannot modify system properties"
          },
          "404": {
            "description": "Property or option not found"
          },
          "409": {
            "description": "An option with that value already exists"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entities/bulk": {
      "post": {
        "tags": ["Properties"],
        "summary": "Get properties for multiple entities in bulk (public endpoint with user auth)",
        "description": "Only returns properties for entities the user has view permission for.\nEntities without permission are silently omitted from the response.",
        "operationId": "get_bulk_entity_properties",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkEntityPropertiesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Bulk entity properties retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/EntityPropertiesResponse"
                  },
                  "propertyNames": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body"
          },
          "403": {
            "description": "Forbidden - User does not have permission"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entities/{entity_type}/{entity_id}": {
      "get": {
        "tags": ["Properties"],
        "summary": "Get all properties for an entity",
        "operationId": "get_entity_properties",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Canonical entity type; tasks use DOCUMENT",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyTargetEntityType"
            }
          },
          {
            "name": "entity_id",
            "in": "path",
            "description": "Entity ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_metadata",
            "in": "query",
            "description": "Whether to include property metadata (default: false)",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity properties retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityPropertiesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid entity type"
          },
          "403": {
            "description": "Forbidden - User does not have permission to view this entity"
          },
          "404": {
            "description": "Entity not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entities/{entity_type}/{entity_id}/options/bulk": {
      "post": {
        "tags": ["Properties"],
        "summary": "Apply a complete tag-picker selection across an entity's multi-select\nproperties in one request.",
        "description": "Each property change is expressed as an option delta and applied to the\ncurrent stored value under a per-row lock inside a single transaction, so the\nselection persists atomically and composes with concurrent edits instead of\nclobbering them. Returns the reconciled final option ids per property for\ncache reconciliation.",
        "operationId": "bulk_update_entity_property_options",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Canonical entity type; tasks use DOCUMENT",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyTargetEntityType"
            }
          },
          {
            "name": "entity_id",
            "in": "path",
            "description": "Entity ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkUpdateEntityPropertyOptionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Options updated; returns final ids per property",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUpdateEntityPropertyOptionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, a property is not multi-select, or an option does not belong to its property"
          },
          "403": {
            "description": "No edit access to the entity"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entities/{entity_type}/{entity_id}/{property_id}": {
      "put": {
        "tags": ["Properties"],
        "summary": "Set or update a property value for an entity, or attach a property without a value",
        "operationId": "set_entity_property",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Canonical entity type; tasks use DOCUMENT",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyTargetEntityType"
            }
          },
          {
            "name": "entity_id",
            "in": "path",
            "description": "Entity ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "property_id",
            "in": "path",
            "description": "Property ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetEntityPropertyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Entity property set successfully (with or without value)"
          },
          "400": {
            "description": "Invalid request or entity type"
          },
          "403": {
            "description": "No edit access to the entity"
          },
          "404": {
            "description": "Entity or property not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entities/{entity_type}/{entity_id}/{property_id}/options/{option_id}": {
      "post": {
        "tags": ["Properties"],
        "summary": "Add a single option to an entity's multi-select property value.",
        "description": "Atomic delta: the option is appended to the current stored value (deduped,\nattaching the property if needed), so concurrent edits to the same value\nmerge rather than overwrite each other. Prefer this over the full-value PUT\nwhen adding one option.",
        "operationId": "add_entity_property_option",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Canonical entity type; tasks use DOCUMENT",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyTargetEntityType"
            }
          },
          {
            "name": "entity_id",
            "in": "path",
            "description": "Entity ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "property_id",
            "in": "path",
            "description": "Property ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "option_id",
            "in": "path",
            "description": "Option ID to add",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Option added successfully"
          },
          "400": {
            "description": "Invalid request, property is not multi-select, or option does not belong to the property"
          },
          "403": {
            "description": "No edit access to the entity"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "delete": {
        "tags": ["Properties"],
        "summary": "Remove a single option from an entity's multi-select property value.",
        "description": "Atomic delta: the option is stripped from the current stored value (a no-op\nif absent), so concurrent edits to the same value merge rather than overwrite\neach other.",
        "operationId": "remove_entity_property_option",
        "parameters": [
          {
            "name": "entity_type",
            "in": "path",
            "description": "Canonical entity type; tasks use DOCUMENT",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PropertyTargetEntityType"
            }
          },
          {
            "name": "entity_id",
            "in": "path",
            "description": "Entity ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "property_id",
            "in": "path",
            "description": "Property ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "option_id",
            "in": "path",
            "description": "Option ID to remove",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Option removed successfully"
          },
          "403": {
            "description": "No edit access to the entity"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/entity_properties/{entity_property_id}": {
      "delete": {
        "tags": ["Properties"],
        "summary": "Remove a specific entity property by its ID",
        "operationId": "delete_entity_property",
        "parameters": [
          {
            "name": "entity_property_id",
            "in": "path",
            "description": "Entity Property ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Entity property removed successfully"
          },
          "403": {
            "description": "Property is required and cannot be removed, or no edit access"
          },
          "404": {
            "description": "Entity property not found"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/options/bulk": {
      "post": {
        "tags": ["Properties"],
        "summary": "Apply one shared option delta (add / remove option ids on a single\nmulti-select property) to many entities in one request — e.g. tag a set of\nemails with one label.",
        "description": "Best-effort per entity: one edit receipt is minted per entity, entities the\ncaller can't edit are reported as `skipped_no_permission` (mirroring the\nread path, which silently drops entities the caller can't view), and each\npermitted entity is updated in its own transaction so one entity failing\ndoes not roll back the others. Returns one result per requested entity in\nrequest order, with the reconciled final option ids for the successes.",
        "operationId": "bulk_update_entities_property_options",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkUpdateEntitiesPropertyOptionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Per-entity results: each entity applied, skipped, or failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUpdateEntitiesPropertyOptionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, the property is not multi-select, or an option does not belong to the property"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/tags": {
      "get": {
        "tags": ["Properties"],
        "summary": "List the caller's tag sets: their personal set, plus their team's set when on a team.\nPure read - a scope with no provisioned definition yet returns an empty set.",
        "operationId": "list_tags",
        "responses": {
          "200": {
            "description": "Tag sets retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TagSetResponse"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      },
      "post": {
        "tags": ["Properties"],
        "summary": "Provision (get-or-create) the caller's tag set for a scope and return it. Called when\nthe caller creates their first label for that scope, so the read path stays side-effect free.",
        "operationId": "ensure_tag_set",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnsureTagSetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Tag set provisioned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagSetResponse"
                }
              }
            }
          },
          "403": {
            "description": "Team membership required for team scope"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/tags/merge": {
      "post": {
        "tags": ["Properties"],
        "summary": "Replace one of the caller's personal labels with an existing team label.",
        "description": "Every entity carrying the personal label is retagged with the team label\n(deduped if it already has both) and the personal label is deleted. The team\nlabel's name and color win. This is the confirmation step after the promote\nendpoint reports a name collision.",
        "operationId": "merge_tag",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MergeTagRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Label merged into the team label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyOptionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Team membership required"
          },
          "404": {
            "description": "Either label was not found in the expected tag set"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/properties/tags/promote": {
      "post": {
        "tags": ["Properties"],
        "summary": "Share one of the caller's personal labels with their team.",
        "description": "The label moves into the team tag set keeping its option id, so every entity\nalready carrying it keeps the label — it just becomes visible to, and usable\nby, the whole team. A 409 means the team already has a label with that name;\nits body carries that label, and confirming the replacement is a call to the\nmerge endpoint with `conflicting_option.id` as `target_option_id`.",
        "operationId": "promote_tag",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromoteTagRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Label moved to the team tag set",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyOptionResponse"
                }
              }
            }
          },
          "403": {
            "description": "Team membership required"
          },
          "404": {
            "description": "Label not found in the caller's tag set"
          },
          "409": {
            "description": "The team already has a label with that name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagPromotionConflictResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AddNumberOptionRequest": {
        "type": "object",
        "description": "Type-safe request to add a number option to a SelectNumber property.",
        "required": ["display_order", "value"],
        "properties": {
          "display_order": {
            "type": "integer",
            "format": "int32"
          },
          "value": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "AddPropertyOptionRequest": {
        "oneOf": [
          {
            "type": "object",
            "description": "Add a string option to a SelectString property",
            "required": ["option", "type"],
            "properties": {
              "option": {
                "$ref": "#/components/schemas/AddStringOptionRequest"
              },
              "type": {
                "type": "string",
                "enum": ["select_string"]
              }
            }
          },
          {
            "type": "object",
            "description": "Add a number option to a SelectNumber property",
            "required": ["option", "type"],
            "properties": {
              "option": {
                "$ref": "#/components/schemas/AddNumberOptionRequest"
              },
              "type": {
                "type": "string",
                "enum": ["select_number"]
              }
            }
          }
        ],
        "description": "Enum for type-safe property option addition requests."
      },
      "AddStringOptionRequest": {
        "type": "object",
        "description": "Type-safe request to add a string option to a SelectString property.",
        "required": ["display_order", "value"],
        "properties": {
          "color": {
            "type": ["string", "null"]
          },
          "display_order": {
            "type": "integer",
            "format": "int32"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "BulkEntityOptionUpdateResult": {
        "type": "object",
        "description": "One entity's result in a cross-entity bulk option update.",
        "required": ["entity_type", "entity_id", "status"],
        "properties": {
          "entity_id": {
            "type": "string",
            "description": "The entity's id this result is for."
          },
          "entity_type": {
            "$ref": "#/components/schemas/PropertyTargetEntityType",
            "description": "The entity's type this result is for."
          },
          "error": {
            "type": ["string", "null"],
            "description": "A human-readable reason, present only when `failed`."
          },
          "option_ids": {
            "type": ["array", "null"],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The entity's reconciled final option ids, present only when `applied`."
          },
          "status": {
            "$ref": "#/components/schemas/BulkEntityOptionUpdateStatus",
            "description": "Whether the delta was applied, skipped, or failed for this entity."
          }
        }
      },
      "BulkEntityOptionUpdateStatus": {
        "type": "string",
        "description": "Per-entity outcome of a cross-entity bulk option update.",
        "enum": ["applied", "skipped_no_permission", "failed"]
      },
      "BulkEntityPropertiesRequest": {
        "type": "object",
        "description": "Request for getting properties for multiple entities in bulk",
        "required": ["entities"],
        "properties": {
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyTargetReference"
            },
            "description": "Array of entity references (entity_id and entity_type pairs)"
          },
          "property_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional: only return properties with these definition IDs. If empty, returns all."
          }
        }
      },
      "BulkUpdateEntitiesPropertyOptionsRequest": {
        "type": "object",
        "description": "Request to apply one shared option delta across several entities in a single\ncall. Mirrors the per-entity bulk endpoint's delta semantics, applied to\nevery listed entity (e.g. tag N emails with one label in one request).",
        "required": ["entities", "property_id"],
        "properties": {
          "add_option_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Options to add to each entity's current value (deduped)."
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyTargetReference"
            },
            "description": "The entities to update. Entities the caller cannot edit are skipped."
          },
          "property_id": {
            "type": "string",
            "format": "uuid",
            "description": "The multi-select property definition changed on every entity."
          },
          "remove_option_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Options to remove from each entity's current value (a no-op if absent)."
          }
        }
      },
      "BulkUpdateEntitiesPropertyOptionsResponse": {
        "type": "object",
        "description": "Response for a cross-entity bulk option update: one result per requested\nentity, in request order.",
        "required": ["results"],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BulkEntityOptionUpdateResult"
            },
            "description": "Per-entity results, aligned to the request's `entities` order."
          }
        }
      },
      "BulkUpdateEntityPropertyOptionsRequest": {
        "type": "object",
        "description": "Request to apply option deltas across one or more of an entity's multi-select\nproperties in a single transaction.",
        "required": ["properties"],
        "properties": {
          "properties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EntityPropertyOptionUpdateRequest"
            },
            "description": "The per-property option changes to apply."
          }
        }
      },
      "BulkUpdateEntityPropertyOptionsResponse": {
        "type": "object",
        "description": "Response for a bulk option update: each property's reconciled final ids.",
        "required": ["properties"],
        "properties": {
          "properties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EntityPropertyOptionSelectionResponse"
            },
            "description": "The final option ids per updated property."
          }
        }
      },
      "CreatePropertyDefinitionRequest": {
        "type": "object",
        "description": "Request to create a new property definition.",
        "required": ["scope", "display_name", "data_type"],
        "properties": {
          "data_type": {
            "$ref": "#/components/schemas/PropertyDataType"
          },
          "display_name": {
            "type": "string"
          },
          "scope": {
            "$ref": "#/components/schemas/CreatePropertyScope"
          }
        }
      },
      "CreatePropertyScope": {
        "type": "string",
        "description": "Ownership scope a client may request when creating a property definition.\nThe owning user or team is derived server-side from the authenticated caller -\nclients never supply owner ids. System properties are not creatable via the API.",
        "enum": ["user", "team"]
      },
      "DataType": {
        "type": "string",
        "description": "Data type for property values, determining storage and validation.",
        "enum": [
          "BOOLEAN",
          "DATE",
          "DATE_RANGE",
          "NUMBER",
          "STRING",
          "SELECT_NUMBER",
          "SELECT_STRING",
          "TAG",
          "ENTITY",
          "LINK"
        ]
      },
      "DateRange": {
        "type": "object",
        "description": "A span of time from `start` to `end`, both included. The end is never\nbefore the start: a range that would end earlier does not deserialize.",
        "required": ["start", "end"],
        "properties": {
          "end": {
            "type": "string",
            "format": "date-time"
          },
          "start": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EnsureTagSetRequest": {
        "type": "object",
        "description": "Request to provision (get-or-create) the caller's tag set for a scope.",
        "required": ["scope"],
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/TagScope"
          }
        }
      },
      "EntityPropertiesResponse": {
        "type": "object",
        "description": "Response for document/entity properties endpoint.",
        "required": ["entity_id", "properties"],
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "properties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EntityPropertyWithDefinition"
            }
          }
        }
      },
      "EntityProperty": {
        "type": "object",
        "description": "Assignment of a property definition to a specific entity (service representation).",
        "required": [
          "id",
          "entity_id",
          "entity_type",
          "property_definition_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "entity_id": {
            "type": "string"
          },
          "entity_type": {
            "$ref": "#/components/schemas/EntityType"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "property_definition_id": {
            "type": "string",
            "format": "uuid"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EntityPropertyOptionSelectionResponse": {
        "type": "object",
        "description": "The reconciled final option ids stored for one property after a bulk update.",
        "required": ["property_id", "option_ids"],
        "properties": {
          "option_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The final option ids the server persisted, in stored order."
          },
          "property_id": {
            "type": "string",
            "format": "uuid",
            "description": "The property definition the options belong to."
          }
        }
      },
      "EntityPropertyOptionUpdateRequest": {
        "type": "object",
        "description": "One property's option changes in a bulk selection update. The change is a\ndelta (options to add / remove) so it composes with concurrent edits rather\nthan replacing the whole value.",
        "required": ["property_id"],
        "properties": {
          "add_option_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Options to add (deduped against the current value)."
          },
          "property_id": {
            "type": "string",
            "format": "uuid",
            "description": "The multi-select property definition being changed."
          },
          "remove_option_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Options to remove (a no-op if not present)."
          }
        }
      },
      "EntityPropertyResponse": {
        "type": "object",
        "description": "Entity property response (API representation).",
        "required": ["id", "entityId", "entityType", "propertyDefinitionId"],
        "properties": {
          "createdAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "entityId": {
            "type": "string"
          },
          "entityType": {
            "$ref": "#/components/schemas/EntityType"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "propertyDefinitionId": {
            "type": "string",
            "format": "uuid"
          },
          "updatedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "EntityPropertyWithDefinition": {
        "type": "object",
        "description": "Entity property with its definition, value, and options (service representation).",
        "required": ["property", "definition"],
        "properties": {
          "definition": {
            "$ref": "#/components/schemas/PropertyDefinition"
          },
          "options": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/PropertyOption"
            }
          },
          "property": {
            "$ref": "#/components/schemas/EntityProperty"
          },
          "value": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PropertyValue"
              }
            ]
          }
        }
      },
      "EntityPropertyWithDefinitionResponse": {
        "type": "object",
        "description": "Entity property with definition response (API representation).",
        "required": ["property", "definition"],
        "properties": {
          "definition": {
            "$ref": "#/components/schemas/PropertyDefinitionDetailResponse"
          },
          "options": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/PropertyOptionResponse"
            }
          },
          "property": {
            "$ref": "#/components/schemas/EntityPropertyResponse"
          },
          "value": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PropertyValue"
              }
            ]
          }
        }
      },
      "EntityQueryParams": {
        "type": "object",
        "description": "Query parameters for entity properties endpoint.",
        "properties": {
          "include_metadata": {
            "type": "boolean",
            "description": "Whether to include system metadata properties (default: false)"
          }
        }
      },
      "EntityReference": {
        "type": "object",
        "description": "Entity reference for entity-type property values.",
        "required": ["entity_id", "entity_type"],
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "entity_type": {
            "$ref": "#/components/schemas/EntityType"
          },
          "specific_message_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "For CHANNEL, CHAT, THREAD entity types - optional specific message ID.\nThis allows referencing a specific message within a thread/channel/chat."
          }
        }
      },
      "EntityType": {
        "type": "string",
        "description": "Type of entity that can be referenced by entity properties.",
        "enum": [
          "CALENDAR_EVENT",
          "CALL_RECORD",
          "CHANNEL",
          "CHAT",
          "COMPANY",
          "DATABASE_ROW",
          "CONTACT",
          "DOCUMENT",
          "INITIATIVE",
          "PROJECT",
          "TASK",
          "THREAD",
          "USER"
        ]
      },
      "ListPropertiesQuery": {
        "type": "object",
        "description": "Query parameters for listing properties",
        "required": ["scope"],
        "properties": {
          "for_entity_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EntityType",
                "description": "Filter properties applicable to a specific entity type.\nWhen provided, excludes properties that cannot be attached to this entity type\n(e.g., Parent Task and Subtasks are excluded for non-task entities)."
              }
            ]
          },
          "include_options": {
            "type": "boolean",
            "description": "Whether to include property options in the response"
          },
          "scope": {
            "$ref": "#/components/schemas/PropertyScope",
            "description": "Scope filter for properties"
          }
        }
      },
      "MergeTagRequest": {
        "type": "object",
        "description": "Request to replace a personal label with an existing team label.",
        "required": ["option_id", "target_option_id"],
        "properties": {
          "option_id": {
            "type": "string",
            "format": "uuid",
            "description": "The personal label to retire."
          },
          "target_option_id": {
            "type": "string",
            "format": "uuid",
            "description": "The team label every entity carrying `option_id` is retagged with."
          }
        }
      },
      "PromoteTagRequest": {
        "type": "object",
        "description": "Request to share one of the caller's personal labels with their team.",
        "required": ["option_id"],
        "properties": {
          "option_id": {
            "type": "string",
            "format": "uuid",
            "description": "The personal label to move into the team tag set."
          }
        }
      },
      "PropertyDataType": {
        "oneOf": [
          {
            "type": "object",
            "description": "Boolean true/false values.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["boolean"]
              }
            }
          },
          {
            "type": "object",
            "description": "Date and time values.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["date"]
              }
            }
          },
          {
            "type": "object",
            "description": "A span from a start date-time to an end one.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["date_range"]
              }
            }
          },
          {
            "type": "object",
            "description": "Numeric values.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["number"]
              }
            }
          },
          {
            "type": "object",
            "description": "String/text values.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["string"]
              }
            }
          },
          {
            "type": "object",
            "description": "Select property with numeric options.",
            "required": ["options", "multi", "type"],
            "properties": {
              "multi": {
                "type": "boolean"
              },
              "options": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SelectNumberOption"
                }
              },
              "type": {
                "type": "string",
                "enum": ["select_number"]
              }
            }
          },
          {
            "type": "object",
            "description": "Select property with string options.",
            "required": ["options", "multi", "type"],
            "properties": {
              "multi": {
                "type": "boolean"
              },
              "options": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SelectStringOption"
                }
              },
              "type": {
                "type": "string",
                "enum": ["select_string"]
              }
            }
          },
          {
            "type": "object",
            "description": "Entity reference property.",
            "required": ["multi", "type"],
            "properties": {
              "multi": {
                "type": "boolean"
              },
              "specific_type": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/EntityType"
                  }
                ]
              },
              "type": {
                "type": "string",
                "enum": ["entity"]
              }
            }
          },
          {
            "type": "object",
            "description": "Link property.",
            "required": ["multi", "type"],
            "properties": {
              "multi": {
                "type": "boolean"
              },
              "type": {
                "type": "string",
                "enum": ["link"]
              }
            }
          }
        ],
        "description": "Data type with embedded options for requests - provides compile-time validation."
      },
      "PropertyDefinition": {
        "type": "object",
        "description": "Property definition model (service representation).",
        "required": [
          "id",
          "owner",
          "display_name",
          "data_type",
          "is_multi_select",
          "specific_entity_type",
          "created_at",
          "updated_at",
          "is_system",
          "is_metadata"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data_type": {
            "$ref": "#/components/schemas/DataType"
          },
          "display_name": {
            "type": "string"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "is_metadata": {
            "type": "boolean",
            "description": "Flag to indicate if this is a system-generated metadata property.\nNot stored in database - computed at service layer."
          },
          "is_multi_select": {
            "type": "boolean"
          },
          "is_system": {
            "type": "boolean",
            "description": "Flag to indicate if this is a system property (stored in DB)."
          },
          "owner": {
            "$ref": "#/components/schemas/PropertyOwner"
          },
          "specific_entity_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EntityType"
              }
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PropertyDefinitionDetailResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PropertyOwner"
          },
          {
            "type": "object",
            "required": [
              "id",
              "displayName",
              "dataType",
              "isMultiSelect",
              "isSystem",
              "isMetadata"
            ],
            "properties": {
              "createdAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "dataType": {
                "$ref": "#/components/schemas/DataType"
              },
              "displayName": {
                "type": "string"
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "isMetadata": {
                "type": "boolean",
                "description": "Flag to indicate if this is a system-generated metadata property"
              },
              "isMultiSelect": {
                "type": "boolean"
              },
              "isSystem": {
                "type": "boolean",
                "description": "Flag to indicate if this is a system property (managed by the system)"
              },
              "specificEntityType": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/EntityType"
                  }
                ]
              },
              "updatedAt": {
                "type": ["string", "null"],
                "format": "date-time"
              }
            }
          }
        ],
        "description": "Property definition response (API representation)."
      },
      "PropertyDefinitionResponse": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PropertyDefinition"
          },
          {
            "$ref": "#/components/schemas/PropertyDefinitionWithOptions"
          }
        ],
        "description": "Response for property definition with optional property options"
      },
      "PropertyDefinitionWithOptions": {
        "type": "object",
        "description": "Property definition with its associated options (service representation).",
        "required": ["definition", "property_options"],
        "properties": {
          "definition": {
            "$ref": "#/components/schemas/PropertyDefinition"
          },
          "property_options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyOption"
            }
          }
        }
      },
      "PropertyDefinitionWithOptionsResponse": {
        "type": "object",
        "description": "Property definition with options response.",
        "required": ["definition", "propertyOptions"],
        "properties": {
          "definition": {
            "$ref": "#/components/schemas/PropertyDefinitionDetailResponse"
          },
          "propertyOptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyOptionResponse"
            }
          }
        }
      },
      "PropertyOption": {
        "type": "object",
        "description": "A selectable option for select-type properties (service representation).",
        "required": [
          "id",
          "property_definition_id",
          "display_order",
          "value",
          "color",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "color": {
            "type": ["string", "null"]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "display_order": {
            "type": "integer",
            "format": "int32"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "property_definition_id": {
            "type": "string",
            "format": "uuid"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "value": {
            "$ref": "#/components/schemas/PropertyOptionValue"
          }
        }
      },
      "PropertyOptionResponse": {
        "type": "object",
        "description": "Property option response (API representation).",
        "required": ["id", "propertyDefinitionId", "displayOrder", "value"],
        "properties": {
          "color": {
            "type": ["string", "null"]
          },
          "displayOrder": {
            "type": "integer",
            "format": "int32"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "propertyDefinitionId": {
            "type": "string",
            "format": "uuid"
          },
          "value": {
            "$ref": "#/components/schemas/PropertyOptionValue"
          }
        }
      },
      "PropertyOptionValue": {
        "oneOf": [
          {
            "type": "object",
            "description": "String value for SelectString properties",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["string"]
              },
              "value": {
                "type": "string",
                "description": "String value for SelectString properties"
              }
            }
          },
          {
            "type": "object",
            "description": "Number value for SelectNumber properties",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["number"]
              },
              "value": {
                "type": "number",
                "format": "double",
                "description": "Number value for SelectNumber properties"
              }
            }
          }
        ],
        "description": "The value of a property option - either a string or a number."
      },
      "PropertyOwner": {
        "oneOf": [
          {
            "type": "object",
            "description": "User-scoped property.",
            "required": ["user_id", "scope"],
            "properties": {
              "scope": {
                "type": "string",
                "enum": ["user"]
              },
              "user_id": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "description": "Team-scoped property.",
            "required": ["team_id", "scope"],
            "properties": {
              "scope": {
                "type": "string",
                "enum": ["team"]
              },
              "team_id": {
                "type": "string",
                "format": "uuid"
              }
            }
          },
          {
            "type": "object",
            "description": "Database-scoped property: the definition is a column of one Macro\ndatabase and is invisible to the shared user/team property namespace.",
            "required": ["database_id", "scope"],
            "properties": {
              "database_id": {
                "type": "string",
                "format": "uuid"
              },
              "scope": {
                "type": "string",
                "enum": ["database"]
              }
            }
          },
          {
            "type": "object",
            "description": "System-owned property (no user, team, or database owner).",
            "required": ["scope"],
            "properties": {
              "scope": {
                "type": "string",
                "enum": ["system"]
              }
            }
          }
        ],
        "description": "Defines who owns a property - user-scoped, team-scoped, database-scoped, or system."
      },
      "PropertyScope": {
        "type": "string",
        "description": "Scope filter for property queries",
        "enum": ["user", "team", "system", "all"]
      },
      "PropertyTargetEntityType": {
        "type": "string",
        "description": "Canonical type of an entity receiving properties.\n\nTasks are documents at API boundaries. `Task` intentionally does not exist\nhere; task classification is resolved by the properties domain from the\ndocument subtype.",
        "enum": [
          "CALL_RECORD",
          "CHANNEL",
          "CHAT",
          "COMPANY",
          "DATABASE_ROW",
          "DOCUMENT",
          "INITIATIVE",
          "PROJECT",
          "THREAD",
          "USER"
        ]
      },
      "PropertyTargetReference": {
        "type": "object",
        "description": "Canonical reference to an entity receiving properties.",
        "required": ["entity_id", "entity_type"],
        "properties": {
          "entity_id": {
            "type": "string",
            "description": "Entity identifier."
          },
          "entity_type": {
            "$ref": "#/components/schemas/PropertyTargetEntityType",
            "description": "Canonical entity type."
          }
        }
      },
      "PropertyValue": {
        "oneOf": [
          {
            "type": "object",
            "description": "Boolean value\nSerializes as: {\"type\": \"Boolean\", \"value\": true}",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["Boolean"]
              },
              "value": {
                "type": "boolean",
                "description": "Boolean value\nSerializes as: {\"type\": \"Boolean\", \"value\": true}"
              }
            }
          },
          {
            "type": "object",
            "description": "Numeric value\nSerializes as: {\"type\": \"Number\", \"value\": 42.5}",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["Number"]
              },
              "value": {
                "type": "number",
                "format": "double",
                "description": "Numeric value\nSerializes as: {\"type\": \"Number\", \"value\": 42.5}"
              }
            }
          },
          {
            "type": "object",
            "description": "String value\nSerializes as: {\"type\": \"String\", \"value\": \"text\"}",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["String"]
              },
              "value": {
                "type": "string",
                "description": "String value\nSerializes as: {\"type\": \"String\", \"value\": \"text\"}"
              }
            }
          },
          {
            "type": "object",
            "description": "Date/timestamp value\nSerializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"}",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["Date"]
              },
              "value": {
                "type": "string",
                "format": "date-time",
                "description": "Date/timestamp value\nSerializes as: {\"type\": \"Date\", \"value\": \"2025-01-01T00:00:00Z\"}"
              }
            }
          },
          {
            "type": "object",
            "description": "Date range value\nSerializes as: {\"type\": \"DateRange\", \"value\": {\"start\": \"2025-01-01T00:00:00Z\", \"end\": \"2025-01-31T00:00:00Z\"}}",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["DateRange"]
              },
              "value": {
                "$ref": "#/components/schemas/DateRange",
                "description": "Date range value\nSerializes as: {\"type\": \"DateRange\", \"value\": {\"start\": \"2025-01-01T00:00:00Z\", \"end\": \"2025-01-31T00:00:00Z\"}}"
              }
            }
          },
          {
            "type": "object",
            "description": "Select option(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1)\nMulti-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+)",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["SelectOption"]
              },
              "value": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Select option(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"SelectOption\", \"value\": [\"uuid\"]} (length 0 or 1)\nMulti-select: {\"type\": \"SelectOption\", \"value\": [\"uuid1\", \"uuid2\", ...]} (length 0+)"
              }
            }
          },
          {
            "type": "object",
            "description": "Entity reference(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1)\nMulti-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+)",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["EntityReference"]
              },
              "value": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EntityReference"
                },
                "description": "Entity reference(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"EntityReference\", \"value\": [{...}]} (length 0 or 1)\nMulti-select: {\"type\": \"EntityReference\", \"value\": [{...}, {...}, ...]} (length 0+)"
              }
            }
          },
          {
            "type": "object",
            "description": "Link value(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1)\nMulti-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+)",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["Link"]
              },
              "value": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Link value(s) - always an array (check is_multi_select to determine if single or multi)\nSingle-select: {\"type\": \"Link\", \"value\": [\"https://example.com\"]} (length 0 or 1)\nMulti-select: {\"type\": \"Link\", \"value\": [\"https://example.com\", \"https://other.com\"]} (length 0+)"
              }
            }
          }
        ],
        "description": "Property value (service representation).\n\nRepresents the actual value stored for an entity property.\nThis is serialized to/from JSONB in the database."
      },
      "SelectNumberOption": {
        "type": "object",
        "description": "Option for select number properties in requests.",
        "required": ["display_order", "value"],
        "properties": {
          "display_order": {
            "type": "integer",
            "format": "int32"
          },
          "value": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "SelectStringOption": {
        "type": "object",
        "description": "Option for select-type properties in requests.",
        "required": ["display_order", "value"],
        "properties": {
          "display_order": {
            "type": "integer",
            "format": "int32"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "SetEntityPropertyRequest": {
        "type": "object",
        "description": "Type-safe request for setting entity property values.",
        "properties": {
          "value": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SetPropertyValue",
                "description": "The value to set for the property. If None, the property is attached to the entity without a value."
              }
            ]
          }
        }
      },
      "SetPropertyValue": {
        "oneOf": [
          {
            "type": "object",
            "description": "Boolean true/false value",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["boolean"]
              },
              "value": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "description": "Date and time value",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["date"]
              },
              "value": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          {
            "type": "object",
            "description": "Date range value",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["date_range"]
              },
              "value": {
                "$ref": "#/components/schemas/DateRange"
              }
            }
          },
          {
            "type": "object",
            "description": "Numeric value",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["number"]
              },
              "value": {
                "type": "number",
                "format": "double"
              }
            }
          },
          {
            "type": "object",
            "description": "String/text value",
            "required": ["value", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["string"]
              },
              "value": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "description": "Select option by ID (for select-type properties)",
            "required": ["option_id", "type"],
            "properties": {
              "option_id": {
                "type": "string",
                "format": "uuid"
              },
              "type": {
                "type": "string",
                "enum": ["select_option"]
              }
            }
          },
          {
            "type": "object",
            "description": "Multiple select options by ID (for multi-select properties)",
            "required": ["option_ids", "type"],
            "properties": {
              "option_ids": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "type": {
                "type": "string",
                "enum": ["multi_select_option"]
              }
            }
          },
          {
            "type": "object",
            "description": "Entity reference",
            "required": ["reference", "type"],
            "properties": {
              "reference": {
                "$ref": "#/components/schemas/EntityReference"
              },
              "type": {
                "type": "string",
                "enum": ["entity_reference"]
              }
            }
          },
          {
            "type": "object",
            "description": "Multiple entity references (for multi-select entity properties)",
            "required": ["references", "type"],
            "properties": {
              "references": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EntityReference"
                }
              },
              "type": {
                "type": "string",
                "enum": ["multi_entity_reference"]
              }
            }
          },
          {
            "type": "object",
            "description": "Link value",
            "required": ["url", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["link"]
              },
              "url": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "description": "Multiple link values (for multi-select link properties)",
            "required": ["urls", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["multi_link"]
              },
              "urls": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ],
        "description": "Type-safe enum for setting entity property values - provides compile-time validation."
      },
      "TagPromotionConflictResponse": {
        "type": "object",
        "description": "Body returned when a promotion collides with a label the team already has.\nThe caller confirms with the user, then calls the merge endpoint with\n`conflicting_option.id` as the target.",
        "required": ["message", "conflicting_option"],
        "properties": {
          "conflicting_option": {
            "$ref": "#/components/schemas/PropertyOptionResponse",
            "description": "The team label that already uses this name."
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of the collision."
          }
        }
      },
      "TagScope": {
        "type": "string",
        "description": "Which owner a tag set belongs to.",
        "enum": ["user", "team"]
      },
      "TagSetResponse": {
        "type": "object",
        "description": "A tag set the caller can use. `definition` is absent until the set is provisioned\n(on first label create), in which case `options` is empty.",
        "required": ["scope", "options"],
        "properties": {
          "definition": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PropertyDefinitionDetailResponse"
              }
            ]
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyOptionResponse"
            }
          },
          "scope": {
            "$ref": "#/components/schemas/TagScope"
          }
        }
      },
      "UpdatePropertyOptionRequest": {
        "type": "object",
        "description": "Request to update a property option in place. Omitted fields keep their current value.\nThe option id is preserved, so the change propagates to every entity referencing it.",
        "properties": {
          "color": {
            "type": ["string", "null"],
            "description": "New color as a hex string like `#RRGGBB`."
          },
          "display_order": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "New display order."
          },
          "value": {
            "type": ["string", "null"],
            "description": "New string value (label text). Only valid for SelectString and Tag properties."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "properties service",
      "description": "Macro Properties Service"
    }
  ]
}