{"openapi":"3.0.0","info":{"title":"Afineo Webservices API — preferences","description":"Module `preferences` of the Afineo API v3 (4 endpoints).\n\nManage display preferences per library context: column visibility, sort order, and layout settings. These control how asset lists are presented to users.\n\nFull specification: https://api.afineo.io/openapi.json","version":"3.0.0","contact":{"name":"Afineo Solutions","url":"https://www.afineo.com"},"x-logo":{"url":"./logo.png","altText":"Afineo - Powerful Data, Powerful People"}},"servers":[{"url":"https://{instance}.afineo.io","description":"Afineo instance","variables":{"instance":{"description":"Your Afineo instance name","default":"client"}}}],"tags":[{"name":"preferences","description":"Manage display preferences per library context: column visibility, sort order, and layout settings. These control how asset lists are presented to users."}],"paths":{"/api/v3/preferences/full/":{"post":{"tags":["preferences"],"summary":"Get all preferences with details","description":"## Purpose\n\nReturns all user preferences for a class with complete configuration (context, type/node assignments, attributes).\n\n## Contexts\n\n- `general`: Global preferences\n- `type`: Per asset-type preferences\n- `node`: Per node preferences\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preference list response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Preference ID"},"code":{"type":"string","example":"my_preference_code","description":"Preference code"},"label":{"type":"string","example":"Display in list","description":"Preference label"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"description":"Array of tags (can be empty)"},"context":{"type":"array","items":{"type":"string","enum":["general","type","node"]},"example":["general","type"],"description":"Array of applicable contexts. Possible values: general, type, node"},"results_total":{"type":"integer","example":2,"description":"Total number of items for this preference"},"items":{"type":"array","items":{"type":"object","properties":{"type_id":{"type":"integer","example":5,"description":"Asset type ID (0 for global)"},"type_label":{"type":"string","example":"Product","description":"Asset type label (empty for global)"},"node_id":{"type":"integer","example":0,"description":"Node ID (0 for global)"},"attributes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":125,"description":"Attribute ID"},"label":{"type":"string","example":"Name","description":"Attribute label"},"order":{"type":"integer","example":1,"description":"Display order"}},"required":["id","label","order"]},"description":"Array of attributes for this type/node combination"}},"required":["type_id","type_label","node_id","attributes"]},"description":"Array of preference configurations by type and node"}},"required":["id","code","label","tags","context","results_total","items"]},"description":"Array of preferences with their configurations"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error, 0 = class not found)"},"status_message":{"type":"string","example":"Class not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4}},"required":["class_id"]}}}}}},"/api/v3/preferences/get/":{"post":{"tags":["preferences"],"summary":"Get preference by context","description":"## Purpose\n\nReturns preference configuration for a specific context (general, type, or node).\n\n## Context Usage\n\n- `general`: No context_id needed\n- `type`: Provide type_id as context_id\n- `node`: Provide node_id as context_id\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preference details response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Preference ID"},"code":{"type":"string","example":"my_preference_code","description":"Preference code"},"label":{"type":"string","example":"Display in list","description":"Preference label"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"description":"Array of tags (can be empty)"},"context":{"type":"array","items":{"type":"string","enum":["general","type","node"]},"example":["general","type"],"description":"Array of applicable contexts. Possible values: general, type, node"},"type_id":{"type":"integer","example":5,"description":"Asset type ID (0 for global)"},"type_label":{"type":"string","example":"Product","description":"Asset type label (empty for global)"},"node_id":{"type":"integer","example":0,"description":"Node ID (0 for global)"},"attributes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":125,"description":"Attribute ID"},"label":{"type":"string","example":"Name","description":"Attribute label"},"order":{"type":"integer","example":1,"description":"Display order"}},"required":["id","label","order"]},"description":"Array of attributes"}},"required":["id","code","label","tags","context","type_id","type_label","node_id","attributes"]}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error)"},"status_message":{"type":"string","example":"Preference not found","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"id":{"type":"integer","description":"Preference ID. Use POST /api/v3/preferences/list to get available preferences.","example":1},"context":{"type":"string","description":"Context filter: \"general\" (global), \"type\" (per asset-type), or \"node\" (per node).","enum":["general","type","node"],"example":"type"},"context_id":{"type":"integer","description":"Context-dependent ID. If context=\"type\": provide type_id (use POST /api/v3/types/list with class_id to get type IDs). If context=\"node\": provide project node_id (use POST /api/v3/projects/list with class_id to get project node IDs). Not required if context=\"general\".","example":5}},"required":["class_id","id","context"]}}}}}},"/api/v3/preferences/list/":{"post":{"tags":["preferences"],"summary":"List preferences (simplified)","description":"## Purpose\n\nReturns simplified preference list (id, code, label, tags, context) without attribute details.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preference list response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Preference ID"},"code":{"type":"string","example":"my_preference_code","description":"Preference code"},"label":{"type":"string","example":"Display in list","description":"Preference label"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"description":"Array of tags (can be empty)"},"context":{"type":"array","items":{"type":"string","enum":["general","type","node"]},"example":["general","type"],"description":"Array of applicable contexts. Possible values: general, type, node"}},"required":["id","code","label","tags","context"]},"description":"Array of preferences with id and label"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error, 0 = class not found)"},"status_message":{"type":"string","example":"Class not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4}},"required":["class_id"]}}}}}},"/api/v3/preferences/update/":{"post":{"tags":["preferences"],"summary":"Update preference attributes","description":"## Purpose\n\nUpdates the list of attributes assigned to a preference for a given context (general, type, or node).\n\n## Behavior\n\nThis is a **complete replacement** operation: the provided `attribute_ids` array replaces all existing attributes for the specified preference and context. To remove all attributes, pass an empty array.\n\n## Context Usage\n\n- `general`: Updates global preference (no context_id needed, type_id=0, node_id=0)\n- `type`: Updates preference for a specific asset type (provide context_id = type_id)\n- `node`: Updates preference for a specific tree node (provide context_id = node_id)\n\n## Important\n\n- The preference must support the requested context (check its `application` code via preferences/get or preferences/list)\n- Attribute IDs must be valid role IDs from the library. Use POST /api/v3/attributes/list to get available attributes.\n- Order of attributes is preserved as provided in the array.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Preference update response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"Preference updated successfully","description":"Status message"},"result":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Preference ID"},"context":{"type":"string","example":"general","description":"Context that was updated"},"context_id":{"type":"integer","example":0,"description":"Context ID (0 for general)"},"attributes_count":{"type":"integer","example":3,"description":"Number of attributes assigned"}},"required":["id","context","context_id","attributes_count"]}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":2,"description":"Status code (2 = validation error, 3 = not found)"},"status_message":{"type":"string","example":"Preference not found","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"id":{"type":"integer","description":"Preference ID to update. Use POST /api/v3/preferences/list to get available preferences.","example":1},"context":{"type":"string","description":"Context level: \"general\" (library-wide), \"type\" (per asset-type), or \"node\" (per tree node).","enum":["general","type","node"],"example":"general"},"context_id":{"type":"integer","description":"Context-dependent ID. Required when context=\"type\" (provide type_id, use POST /api/v3/types/list) or context=\"node\" (provide node_id, use POST /api/v3/projects/list). Defaults to 0 when omitted (general context).","example":5},"attribute_ids":{"type":"array","description":"Array of attribute/role IDs to assign to this preference. Replaces all existing attributes. Pass empty array [] to clear. Use POST /api/v3/attributes/list to get available attribute IDs.","example":[101,102,103],"items":{"type":"integer"}}},"required":["class_id","id","context","attribute_ids"]}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token generated with /api/v3/token/get/"}}}}