Properties and asset search

The REST API and MCP connector use the same properties as Settings → Properties. You can create fields, manage their options, archive or restore them, read and update asset values, and find assets by those values.

For example, “Show all models with Season set to Spring” involves two steps: list the property definitions to find the Season and Spring IDs, then search models using those IDs. Names can change; IDs stay stable.

Access and supported assets

REST requests use your workspace API key in X-API-Key. MCP calls use your connected account; pass workspaceId to select a workspace or omit it to use your current workspace. Both require a plan with API access.

Workspace owners and admins can change definitions and options, including archiving, restoring, reordering, merging and copying tags. Workspace members can read definitions and read or update asset values. For REST, definition permissions are checked against the API key’s creator.

The assetType values are MODEL, VARIANT, PROJECT, TEMPLATE, MATERIAL, PROP, RENDER, DECAL, BACKPLATE, and STYLE. Reads, writes and property searches are restricted to assets owned by the selected workspace; shared public assets owned elsewhere are not included. Model searches exclude sample models, and generic asset search excludes deleted assets.

Find models by a property

List definitions and options:

curl 'https://api.glossi.io/api/v1/properties?assetType=MODEL' \
  -H "X-API-Key: $GLOSSI_API_KEY"

The response contains properties, each with id, name, stable key, type, appliesTo, options, and archived. Each option has its own id, label, color, sortOrder, and archived flag.

Use the returned IDs to search:

curl 'https://api.glossi.io/api/v1/assets/search' \
  -H "X-API-Key: $GLOSSI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "assetType": "MODEL",
    "properties": [{"propertyId": "season-id", "optionIds": ["spring-id"]}],
    "limit": 25,
    "offset": 0
  }'

The response is { "assetType", "assets", "total", "limit", "offset" }. Each asset includes id, name, assetType, and properties. Filtering happens before pagination and counting. Increase offset by limit until you have retrieved total matches. Limits are 1–100, default 25; offset defaults to 0 and is capped at 100,000.

Models also support a JSON-encoded properties query parameter on the existing list endpoint. This combines with name/status filters and returns the usual models list, now including property values:

curl --get 'https://api.glossi.io/api/v1/models' \
  -H "X-API-Key: $GLOSSI_API_KEY" \
  --data-urlencode 'properties=[{"propertyId":"season-id","optionIds":["spring-id"]}]' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'offset=0'

Filter types

A request can contain up to 30 property filters. An asset must match all filters. Within one optionIds array, matching any of the supplied options is enough.

Date filters use epoch milliseconds and compare the start date. They do not test overlap with a stored date range. isEmpty: true cannot be combined with value operators. Invalid field/operator combinations, unknown options, reversed bounds, and properties belonging to another workspace are rejected.

Explicit archived property or option IDs can still be searched to retrieve historical metadata. By default, listing definitions hides archived properties; use includeArchived=true to discover them. Options carry an archived flag rather than being removed from definition responses.

Create and manage definitions

{
  "name": "Season",
  "type": "SELECT",
  "options": ["Spring", "Summer"],
  "appliesTo": ["MODEL", "PROJECT"]
}

Send this body to POST /properties. Supported types are SELECT, MULTI_SELECT, TEXT, NUMBER, and DATE. Omit appliesTo to allow all ten asset types. Only select types accept predefined options. For a date range, create a DATE property with dateRange: true.

Type and date-range settings are fixed after creation. Rename a field with PATCH /properties/:id; its ID and key stay unchanged. Limits match the app: 30 active properties, 200 options per property, and at most two properties shown on cards for each asset type.

DELETE /properties/:id archives the definition. It preserves its options and every stored asset value. Restore it with PATCH /properties/:id and { "archived": false }. There is no permanent definition-delete endpoint. Archived definitions and options cannot receive new values, but existing values remain readable and can be cleared.

Archive or restore an option using PATCH /properties/:propertyId/options/:optionId with archived. That route also accepts label, nullable hex color, and sortOrder. To consolidate duplicate options, merge fromOptionId into an active intoOptionId; this replaces the source on all asset types, deduplicates multi-select values, and removes the source option.

Read and update asset values

Read one asset with GET /assets/MODEL/:id/properties. Write to up to 100 assets of one type with POST /assets/properties:

{
  "assetType": "MODEL",
  "ids": ["model-a", "model-b"],
  "set": [{ "propertyId": "season-id", "optionIds": ["spring-id"] }],
  "unset": ["old-note-id"],
  "mode": "REPLACE"
}

set changes only the listed properties; other metadata stays intact. unset removes listed property values. REPLACE is the default. ADD unions multi-select options with existing choices; other field types still replace. A property cannot appear in both set and unset, and every asset ID must belong to the selected workspace. The response’s updated count is the number of matched assets, including assets that already held the requested value.

Supply the value field matching the property type: optionIds, text, number, or date with an optional endDate. Dates use epoch milliseconds and are normalized to UTC midnight; the end must be on or after the start. Empty option lists or null/blank values clear the property. Use unset when you want to clear it explicitly.

REST and MCP operations

REST paths below are relative to https://api.glossi.io/api/v1. MCP tools take equivalent named arguments plus optional workspaceId.

Tag conversion matches the app’s model-only behavior: it copies matching model tags into a select property, preserves existing single-select answers, adds to multi-select answers, and keeps the original tags.

With an MCP agent, you can ask:

List our model properties, then show every model whose Season is Spring. Include each model’s property values.

The agent can call list_properties, resolve the IDs, and use list_models or search_assets_by_properties, paging as needed. Number and date filters are available through these APIs even where the library UI does not yet provide those controls.

Expected errors use HTTP 400 for invalid inputs, 403 for insufficient definition-management permissions, and 404 for missing or inaccessible properties/assets. MCP returns the same explanation as a tool error.