{ "openapi": "3.1.0", "info": { "title": "FastAPI", "version": "2.0.0" }, "servers": [ { "url": "https://api-external.zenlytic.com/api/v2", "description": "US" }, { "url": "https://euapi-external.zenlytic.com/api/v2", "description": "EU" } ], "paths": { "/me": { "get": { "tags": [ "Me" ], "summary": "Get Me", "description": "Retrieve your organization and the workspaces you can see.", "operationId": "get_me_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_MeSchema_" }, "example": { "data": { "organization": { "id": "org_123", "name": "Acme Corp" }, "workspaces": [ { "id": "ws_456", "name": "acme-prod" } ] }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } } }, "5XX": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspaces For Organization", "description": "List the workspaces in your organization.\n\nArchived workspaces are excluded unless ``include_archived`` is true.", "operationId": "list_workspaces_for_organization_workspaces_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Archived" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2CollectionResponse_WorkspaceManagerWorkspaceSchema_" }, "example": { "data": [ { "id": "ws_456", "name": "acme-prod", "provision_by_default": true } ], "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create Workspace In Organization", "description": "Create a new workspace in your organization.\n\nRequires workspace_management permission on every workspace you belong to in the\norganization.", "operationId": "create_workspace_in_organization_workspaces_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceSchema" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_CreateWorkspaceResponseSchema_" }, "example": { "data": { "id": "ws_789", "name": "acme-staging", "provision_by_default": false }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}": { "delete": { "tags": [ "Workspaces" ], "summary": "Archive Workspace For Organization", "description": "Archive a workspace in your organization.", "operationId": "archive_workspace_for_organization_workspaces__workspace_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "204": { "description": "Successful Response" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/groups/{group_id}/user_attributes": { "get": { "tags": [ "Groups" ], "summary": "Get Group User Attributes", "description": "List the user attribute values set on a group.\n\nThese apply to every member of the group. When a member is in several groups that set the\nsame attribute, the group with the highest ``user_attribute_precedence`` wins.\n\n``source`` is always ``\"group\"`` and ``source_id`` always matches this group's ID here \u2014\nboth only vary on the member user attributes endpoint, where a value can come from any of a\nmember's groups or be set directly on the member.", "operationId": "get_group_user_attributes_workspaces__workspace_id__groups__group_id__user_attributes_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2CollectionResponse_UserAttributeSchema_" }, "example": { "data": [ { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "west", "data_type": "string", "name": "region", "source": "group", "source_id": "grp_123", "user_attribute_precedence": 1, "is_overridden": false } ], "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "post": { "tags": [ "Groups" ], "summary": "Create Group User Attribute", "description": "Set a user attribute value on a group.\n\n``user_attribute_definition_id`` must reference an existing definition in the workspace. A\ngroup can only set each definition once; a second value for the same definition returns\n409 \u2014 patch the existing value instead.\n\n``value`` must match the definition's ``data_type``: ``YYYY-MM-DD`` for ``date``, a numeric\nstring for ``number``.", "operationId": "create_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserAttributeSchema" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeSchema_" }, "example": { "data": { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "west", "data_type": "string", "name": "region", "source": "group", "source_id": "grp_123", "user_attribute_precedence": 1, "is_overridden": false }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/groups/{group_id}/user_attributes/{user_attribute_id}": { "delete": { "tags": [ "Groups" ], "summary": "Delete Group User Attribute", "description": "Remove a user attribute value from a group.\n\nThe definition itself is untouched \u2014 only this group's value for it is deleted.", "operationId": "delete_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes__user_attribute_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } }, { "name": "user_attribute_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Id" } } ], "responses": { "204": { "description": "Successful Response" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "patch": { "tags": [ "Groups" ], "summary": "Update Group User Attribute", "description": "Update the value of a user attribute already set on a group.\n\nOnly ``value`` is mutable; to point at a different definition, delete this value and\ncreate a new one. ``value`` must match the existing definition's ``data_type``:\n``YYYY-MM-DD`` for ``date``, a numeric string for ``number``.", "operationId": "update_group_user_attribute_workspaces__workspace_id__groups__group_id__user_attributes__user_attribute_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } }, { "name": "user_attribute_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAttributeSchema" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeSchema_" }, "example": { "data": { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "east", "data_type": "string", "name": "region", "source": "group", "source_id": "grp_123", "user_attribute_precedence": 1, "is_overridden": false }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/groups": { "get": { "tags": [ "Groups" ], "summary": "Get Groups", "description": "List every group in the workspace, including the built-in \"All Users\" group.\n\nEach group carries its member ids and its ``user_attribute_precedence``. A warning is\nreturned when two groups in the workspace share a precedence value, since the winning\nuser attribute is then undefined.", "operationId": "get_groups_workspaces__workspace_id__groups_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2CollectionResponse_GroupResponseSchema_" }, "example": { "data": [ { "id": "grp_123", "workspace_id": "ws_456", "name": "Sales", "is_all_users": false, "user_attribute_precedence": 1, "users": [ "usr_111", "usr_222" ] } ], "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "post": { "tags": [ "Groups" ], "summary": "Create Group", "description": "Create a group in the workspace.\n\n``user_attribute_precedence`` must be greater than 0 and decides which group's value wins\nwhen a member belongs to several groups that set the same user attribute. A warning is\nreturned when the new group duplicates an existing precedence value.", "operationId": "create_group_workspaces__workspace_id__groups_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupSchema" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_GroupResponseSchema_" }, "example": { "data": { "id": "grp_123", "workspace_id": "ws_456", "name": "Sales", "is_all_users": false, "user_attribute_precedence": 1, "users": [ "usr_111", "usr_222" ] }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/groups/{group_id}": { "get": { "tags": [ "Groups" ], "summary": "Get Group", "description": "Retrieve a single group in the workspace by id.\n\nReturns 404 if no group with that id exists in the workspace.", "operationId": "get_group_workspaces__workspace_id__groups__group_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_GroupResponseSchema_" }, "example": { "data": { "id": "grp_123", "workspace_id": "ws_456", "name": "Sales", "is_all_users": false, "user_attribute_precedence": 1, "users": [ "usr_111", "usr_222" ] }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "patch": { "tags": [ "Groups" ], "summary": "Update Group", "description": "Update a group's name or user attribute precedence.\n\nThe built-in \"All Users\" group cannot be updated; its membership always tracks the\nworkspace roster. A warning is returned if the update makes this group's precedence\nmatch another group's in the workspace.", "operationId": "update_group_workspaces__workspace_id__groups__group_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupSchema" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_GroupResponseSchema_" }, "example": { "data": { "id": "grp_123", "workspace_id": "ws_456", "name": "Sales Team", "is_all_users": false, "user_attribute_precedence": 2, "users": [ "usr_111", "usr_222" ] }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete Group", "description": "Delete a group and the user attributes attached to it.\n\nMembers are not deleted, only their membership. The built-in \"All Users\" group cannot be\ndeleted.", "operationId": "delete_group_workspaces__workspace_id__groups__group_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Group Id" } } ], "responses": { "204": { "description": "Successful Response" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/members/{member_id}/user_attributes": { "get": { "tags": [ "User Attributes" ], "summary": "Get Member User Attributes", "description": "List the user attribute values that apply to a workspace member.\n\nIncludes values inherited from the member's groups as well as values set directly on the\nmember. ``is_overridden`` marks a group-inherited value that a higher-precedence group's\nvalue, or a value set directly on the member, has superseded - so the effective set is\nthe entries where it is false. ``user_attribute_precedence`` is ``null`` exactly when\n``source`` is ``\"user\"`` (a directly-set value) - only groups carry a precedence.", "operationId": "get_member_user_attributes_workspaces__workspace_id__members__member_id__user_attributes_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2CollectionResponse_UserAttributeSchema_" }, "example": { "data": [ { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "west", "data_type": "string", "name": "region", "source": "user", "source_id": "usr_111", "is_overridden": false }, { "id": "ua_790", "user_attribute_definition_id": "uad_124", "value": "2024-01-15", "data_type": "date", "name": "renewal_date", "source": "group", "source_id": "grp_123", "user_attribute_precedence": 1, "is_overridden": true } ], "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "post": { "tags": [ "User Attributes" ], "summary": "Create Member User Attribute", "description": "Set a user attribute value directly on a workspace member.\n\nA value set here takes precedence over any value the member inherits from a group. Each\nmember can only set a given definition once; a duplicate returns 409 \u2014 patch the existing\nvalue instead.\n\n``value`` must match the definition's ``data_type``: ``YYYY-MM-DD`` for ``date``, a numeric\nstring for ``number``.", "operationId": "create_member_user_attribute_workspaces__workspace_id__members__member_id__user_attributes_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserAttributeSchema" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeSchema_" }, "example": { "data": { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "west", "data_type": "string", "name": "region", "source": "user", "source_id": "usr_111", "is_overridden": false }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/members/{member_id}/user_attributes/{user_attribute_id}": { "delete": { "tags": [ "User Attributes" ], "summary": "Delete Member User Attribute", "description": "Remove a user attribute value set directly on a workspace member.\n\nOnly values set on the member can be deleted here; group-inherited values are managed on\nthe group. Once removed, any group value for that definition applies again.", "operationId": "delete_member_user_attribute_workspaces__workspace_id__members__member_id__user_attributes__user_attribute_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } }, { "name": "user_attribute_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Id" } } ], "responses": { "204": { "description": "Successful Response" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "patch": { "tags": [ "User Attributes" ], "summary": "Update Member User Attribute", "description": "Update the value of a user attribute set directly on a workspace member.\n\nOnly ``value`` is mutable; to point at a different definition, delete this value and\ncreate a new one. ``value`` must match the existing definition's ``data_type``:\n``YYYY-MM-DD`` for ``date``, a numeric string for ``number``.", "operationId": "update_member_user_attribute_workspaces__workspace_id__members__member_id__user_attributes__user_attribute_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } }, { "name": "user_attribute_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAttributeSchema" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeSchema_" }, "example": { "data": { "id": "ua_789", "user_attribute_definition_id": "uad_123", "value": "east", "data_type": "string", "name": "region", "source": "user", "source_id": "usr_111", "is_overridden": false }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/user_attribute_definitions": { "get": { "tags": [ "User Attributes" ], "summary": "Get User Attribute Definitions", "description": "List the user attribute definitions in the workspace.\n\nA definition declares the ``name``, ``label``, and ``data_type`` of an attribute. The\nper-member and per-group endpoints then assign values against these definitions.", "operationId": "get_user_attribute_definitions_workspaces__workspace_id__user_attribute_definitions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2CollectionResponse_UserAttributeDefinitionSchema_" }, "example": { "data": [ { "id": "uad_123", "workspace_id": "ws_456", "name": "region", "data_type": "string", "label": "Region" } ], "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "post": { "tags": [ "User Attributes" ], "summary": "Create User Attribute Definition", "description": "Create a user attribute definition in the workspace.\n\n``name`` must be unique within the workspace; a duplicate returns 409. The ``data_type``\nis fixed at creation time and cannot be changed afterwards.", "operationId": "create_user_attribute_definition_workspaces__workspace_id__user_attribute_definitions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserAttributeDefinitionSchema" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeDefinitionSchema_" }, "example": { "data": { "id": "uad_123", "workspace_id": "ws_456", "name": "region", "data_type": "string", "label": "Region" }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } }, "/workspaces/{workspace_id}/user_attribute_definitions/{user_attribute_definition_id}": { "delete": { "tags": [ "User Attributes" ], "summary": "Delete User Attribute Definition", "description": "Delete a user attribute definition and every value assigned against it.\n\nThis removes the attribute from all members and groups in the workspace.", "operationId": "delete_user_attribute_definition_workspaces__workspace_id__user_attribute_definitions__user_attribute_definition_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "user_attribute_definition_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Definition Id" } } ], "responses": { "204": { "description": "Successful Response" }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } }, "patch": { "tags": [ "User Attributes" ], "summary": "Update User Attribute Definition", "description": "Update a user attribute definition's label.\n\nOnly ``label`` is mutable \u2014 ``name`` and ``data_type`` are fixed once created, because\nassigned values and data model references depend on them.", "operationId": "update_user_attribute_definition_workspaces__workspace_id__user_attribute_definitions__user_attribute_definition_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "user_attribute_definition_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Attribute Definition Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAttributeDefinitionSchema" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2Response_UserAttributeDefinitionSchema_" }, "example": { "data": { "id": "uad_123", "workspace_id": "ws_456", "name": "region", "data_type": "string", "label": "Sales Region" }, "meta": { "status": "success", "errors": [], "warnings": [] } } } } }, "4XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Client Error" }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiV2ErrorResponse" } } }, "description": "Server Error" } } } } }, "components": { "schemas": { "ApiV2CollectionResponse_GroupResponseSchema_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/GroupResponseSchema" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2CollectionResponse[GroupResponseSchema]" }, "ApiV2CollectionResponse_UserAttributeDefinitionSchema_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserAttributeDefinitionSchema" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2CollectionResponse[UserAttributeDefinitionSchema]" }, "ApiV2CollectionResponse_UserAttributeSchema_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserAttributeSchema" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2CollectionResponse[UserAttributeSchema]" }, "ApiV2CollectionResponse_WorkspaceManagerWorkspaceSchema_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkspaceManagerWorkspaceSchema" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2CollectionResponse[WorkspaceManagerWorkspaceSchema]" }, "ApiV2ErrorResponse": { "properties": { "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "meta" ], "title": "ApiV2ErrorResponse" }, "ApiV2Response_CreateWorkspaceResponseSchema_": { "properties": { "data": { "$ref": "#/components/schemas/CreateWorkspaceResponseSchema" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2Response[CreateWorkspaceResponseSchema]" }, "ApiV2Response_GroupResponseSchema_": { "properties": { "data": { "$ref": "#/components/schemas/GroupResponseSchema" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2Response[GroupResponseSchema]" }, "ApiV2Response_MeSchema_": { "properties": { "data": { "$ref": "#/components/schemas/MeSchema" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2Response[MeSchema]" }, "ApiV2Response_UserAttributeDefinitionSchema_": { "properties": { "data": { "$ref": "#/components/schemas/UserAttributeDefinitionSchema" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2Response[UserAttributeDefinitionSchema]" }, "ApiV2Response_UserAttributeSchema_": { "properties": { "data": { "$ref": "#/components/schemas/UserAttributeSchema" }, "meta": { "$ref": "#/components/schemas/MetaSchema" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiV2Response[UserAttributeSchema]" }, "BaseErrorMetadata": { "properties": {}, "type": "object", "title": "BaseErrorMetadata" }, "CreateGroupSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "user_attribute_precedence": { "type": "integer", "title": "User Attribute Precedence", "description": "Must be greater than 0; 0 is reserved for the all_users group." } }, "type": "object", "required": [ "name", "user_attribute_precedence" ], "title": "CreateGroupSchema", "examples": [ { "name": "Sales", "user_attribute_precedence": 1 } ] }, "CreateUserAttributeDefinitionSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "data_type": { "$ref": "#/components/schemas/UserAttributeDataType" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "name", "data_type", "label" ], "title": "CreateUserAttributeDefinitionSchema", "examples": [ { "data_type": "string", "label": "Region", "name": "region" } ] }, "CreateUserAttributeSchema": { "properties": { "user_attribute_definition_id": { "type": "string", "title": "User Attribute Definition Id" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "user_attribute_definition_id", "value" ], "title": "CreateUserAttributeSchema", "examples": [ { "user_attribute_definition_id": "uad_123", "value": "west" } ] }, "CreateWorkspaceResponseSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "provision_by_default": { "type": "boolean", "title": "Provision By Default" } }, "type": "object", "required": [ "id", "name", "provision_by_default" ], "title": "CreateWorkspaceResponseSchema", "examples": [ { "id": "ws_789", "name": "acme-staging", "provision_by_default": false } ] }, "CreateWorkspaceSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "provision_by_default": { "type": "boolean", "title": "Provision By Default", "default": false } }, "type": "object", "required": [ "name" ], "title": "CreateWorkspaceSchema", "examples": [ { "name": "acme-staging", "provision_by_default": false } ] }, "ErrorSchema": { "properties": { "message": { "type": "string", "title": "Message" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "occurred_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Occurred At" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "error_metadata": { "anyOf": [ { "$ref": "#/components/schemas/BaseErrorMetadata" }, { "type": "null" } ] } }, "type": "object", "required": [ "message" ], "title": "ErrorSchema", "examples": [ { "message": "Workspace not found", "occurred_at": "2026-08-05T12:00:00Z", "status_code": 404 } ] }, "GroupResponseSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "workspace_id": { "type": "string", "title": "Workspace Id" }, "name": { "type": "string", "title": "Name" }, "is_all_users": { "type": "boolean", "title": "Is All Users" }, "user_attribute_precedence": { "type": "integer", "title": "User Attribute Precedence" }, "users": { "items": { "type": "string" }, "type": "array", "title": "Users" } }, "type": "object", "required": [ "id", "workspace_id", "name", "is_all_users", "user_attribute_precedence", "users" ], "title": "GroupResponseSchema", "examples": [ { "id": "grp_123", "is_all_users": false, "name": "Sales", "user_attribute_precedence": 1, "users": [ "usr_111", "usr_222" ], "workspace_id": "ws_456" } ] }, "MeSchema": { "properties": { "organization": { "$ref": "#/components/schemas/MyOrganizationSchema" }, "workspaces": { "items": { "$ref": "#/components/schemas/MyWorkspaceSchema" }, "type": "array", "title": "Workspaces" } }, "type": "object", "required": [ "organization", "workspaces" ], "title": "MeSchema", "examples": [ { "organization": { "id": "org_123", "name": "Acme Corp" }, "workspaces": [ { "id": "ws_456", "name": "acme-prod" } ] } ] }, "MetaSchema": { "properties": { "status": { "$ref": "#/components/schemas/ResponseStatus" }, "errors": { "items": { "$ref": "#/components/schemas/ErrorSchema" }, "type": "array", "title": "Errors" }, "warnings": { "items": { "$ref": "#/components/schemas/WarningSchema" }, "type": "array", "title": "Warnings" }, "request_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Source" } }, "type": "object", "required": [ "status" ], "title": "MetaSchema", "examples": [ { "errors": [], "status": "success", "warnings": [] } ] }, "MyOrganizationSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "MyOrganizationSchema", "examples": [ { "id": "org_123", "name": "Acme Corp" } ] }, "MyWorkspaceSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "MyWorkspaceSchema", "examples": [ { "id": "ws_456", "name": "acme-prod" } ] }, "ResponseStatus": { "type": "string", "enum": [ "success", "error" ], "title": "ResponseStatus" }, "UpdateGroupSchema": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "user_attribute_precedence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "User Attribute Precedence", "description": "Must be greater than 0; 0 is reserved for the all_users group." } }, "type": "object", "title": "UpdateGroupSchema", "examples": [ { "name": "Sales Team", "user_attribute_precedence": 2 } ] }, "UpdateUserAttributeDefinitionSchema": { "properties": { "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "label" ], "title": "UpdateUserAttributeDefinitionSchema", "examples": [ { "label": "Sales Region" } ] }, "UpdateUserAttributeSchema": { "properties": { "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "value" ], "title": "UpdateUserAttributeSchema", "examples": [ { "value": "east" } ] }, "UserAttributeDataType": { "type": "string", "enum": [ "string", "number", "date" ], "title": "UserAttributeDataType" }, "UserAttributeDefinitionSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "workspace_id": { "type": "string", "title": "Workspace Id" }, "name": { "type": "string", "title": "Name" }, "data_type": { "$ref": "#/components/schemas/UserAttributeDataType" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "id", "workspace_id", "name", "data_type", "label" ], "title": "UserAttributeDefinitionSchema", "examples": [ { "data_type": "string", "id": "uad_123", "label": "Region", "name": "region", "workspace_id": "ws_456" } ] }, "UserAttributeSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "user_attribute_definition_id": { "type": "string", "title": "User Attribute Definition Id" }, "value": { "type": "string", "title": "Value" }, "data_type": { "$ref": "#/components/schemas/UserAttributeDataType" }, "name": { "type": "string", "title": "Name" }, "source": { "$ref": "#/components/schemas/UserAttributeSource" }, "source_id": { "type": "string", "title": "Source Id" }, "user_attribute_precedence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "User Attribute Precedence" }, "is_overridden": { "type": "boolean", "title": "Is Overridden" } }, "type": "object", "required": [ "id", "user_attribute_definition_id", "value", "data_type", "name", "source", "source_id", "user_attribute_precedence", "is_overridden" ], "title": "UserAttributeSchema", "examples": [ { "data_type": "string", "id": "ua_789", "is_overridden": false, "name": "region", "source": "group", "source_id": "grp_123", "user_attribute_definition_id": "uad_123", "user_attribute_precedence": 1, "value": "west" } ] }, "UserAttributeSource": { "type": "string", "enum": [ "user", "group" ], "title": "UserAttributeSource" }, "WarningSchema": { "properties": { "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "WarningSchema", "examples": [ { "message": "3 rows were skipped due to invalid formatting" } ] }, "WorkspaceManagerWorkspaceSchema": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "provision_by_default": { "type": "boolean", "title": "Provision By Default" }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived At" } }, "type": "object", "required": [ "id", "name", "provision_by_default" ], "title": "WorkspaceManagerWorkspaceSchema", "examples": [ { "id": "ws_456", "name": "acme-prod", "provision_by_default": true } ] } }, "securitySchemes": { "HTTPBearer": { "type": "http", "description": "A Personal Access Token (PAT).", "scheme": "bearer" } } }, "tags": [ { "name": "Org Admin", "x-page-title": "Org Admin", "x-page-icon": "building", "x-page-description": "Organization-wide administration, spanning every workspace you belong to." }, { "name": "Admin", "x-page-title": "Admin", "x-page-icon": "user-shield", "x-page-description": "Administration scoped to a single workspace." }, { "name": "Me", "x-page-title": "Me", "x-page-icon": "id-card", "x-page-description": "Your own organization and workspace access." }, { "name": "Workspaces", "x-parent": "Org Admin", "x-page-title": "Workspaces", "x-page-icon": "layer-group", "x-page-description": "Create, list, and archive workspaces in your organization. Requires an org admin personal access token." }, { "name": "Groups", "x-parent": "Admin", "x-page-title": "Groups", "x-page-icon": "users", "x-page-description": "Manage groups and the user attribute values set on them." }, { "name": "User Attributes", "x-parent": "Admin", "x-page-title": "User Attributes", "x-page-icon": "sliders", "x-page-description": "Define custom attributes and set their values on groups and members." } ] }