{ "components": { "schemas": { "DuplicateZoneRequest": { "type": "object", "properties": { "duplicate_zone": { "description": "duplicate zone. Max length: 11000 (required)", "type": "object", "properties": { "destination_type": { "description": "destination type. Allowed values: NEW_SPACE, SAME_SPACE, EXISTING_SPACE (required)", "type": "string", "enum": [ "NEW_SPACE", "SAME_SPACE", "EXISTING_SPACE" ] }, "space_name": { "pattern": "^(?:[0-9a-zA-Z_~`#%&\\^\\*\\(\\)\\{\\}\\[\\]\\+\\*\\|=\\-\\.\\$@\\?,:;>\\\\'\\/!\\u0080-\\uFFFF\\s<\"]+)$", "description": "space name", "type": "string" }, "deep_copy": { "description": "deep copy", "type": "boolean" }, "zone_name": { "pattern": "^(?:[0-9a-zA-Z_~`#%&\\^\\*\\(\\)\\{\\}\\[\\]\\+\\*\\|=\\-\\.\\$@\\?,:;>\\\\'\\/!\\u0080-\\uFFFF\\s<\"]+)$", "description": "zone name", "type": "string" }, "version_id": { "description": "version id", "type": "string" }, "team_id": { "description": "team id", "type": "string" }, "copy_members": { "description": "copy members", "type": "boolean" }, "destination_space_id": { "description": "destination space id", "type": "string" }, "copy_comments": { "description": "copy comments", "type": "boolean" } }, "required": [ "destination_type" ] } }, "required": [ "duplicate_zone" ] }, "UpdateZoneMetaRequest": { "type": "object", "properties": { "zone_name": { "pattern": "^(?:[0-9a-zA-Z_~`#%&\\^\\*\\(\\)\\{\\}\\[\\]\\+\\*\\|=\\-\\.\\$@\\?,:;>\\\\'\\/!\\u0080-\\uFFFF\\s<\"]+)$", "description": "zone name (required)", "type": "string" } }, "required": [ "zone_name" ] }, "VaniEnvelope": { "description": "Standard Vani response envelope.", "type": "object", "properties": { "data": { "description": "Operation payload. Narrowed per endpoint where a response schema is declared.", "type": "object" }, "message": { "type": "string" }, "request_uri": { "type": "string" }, "status": { "description": "success or error", "type": "string" } }, "required": [ "status" ] }, "CreateZoneRequest": { "type": "object", "properties": { "create_zone": { "description": "create zone. Max length: 11000 (required)", "type": "object", "properties": { "zone_name": { "pattern": "^(?:[0-9a-zA-Z_~`#%&\\^\\*\\(\\)\\{\\}\\[\\]\\+\\*\\|=\\-\\.\\$@\\?,:;>\\\\'\\/!\\u0080-\\uFFFF\\s<\"]+)$", "description": "zone name (required)", "type": "string" }, "template_id": { "description": "template id", "type": "string" } }, "required": [ "zone_name" ] } }, "required": [ "create_zone" ] }, "VaniError": { "description": "Standard Vani error envelope.", "type": "object", "properties": { "error": { "type": "object", "properties": { "details": { "description": "Error code and message, plus any context keys (edition_id, space_id, ...).", "additionalProperties": true, "type": "object", "properties": { "sdk_error_code": { "description": "Raw SDK code, present when the error was not mapped.", "type": "string" }, "error_code": { "type": "string" }, "message": { "type": "string" } } } } }, "request_uri": { "type": "string" }, "status": { "type": "string" } } }, "MoveZoneRequest": { "type": "object", "properties": { "move_zone": { "description": "move zone. Max length: 11000 (required)", "type": "object", "properties": { "destination_type": { "description": "destination type. Allowed values: NEW_SPACE, EXISTING_SPACE (required)", "type": "string", "enum": [ "NEW_SPACE", "EXISTING_SPACE" ] }, "space_name": { "pattern": "^(?:[0-9a-zA-Z_~`#%&\\^\\*\\(\\)\\{\\}\\[\\]\\+\\*\\|=\\-\\.\\$@\\?,:;>\\\\'\\/!\\u0080-\\uFFFF\\s<\"]+)$", "description": "space name", "type": "string" }, "deep_copy": { "description": "deep copy", "type": "boolean" }, "team_id": { "description": "team id", "type": "string" }, "destination_space_id": { "description": "destination space id", "type": "string" }, "copy_comments": { "description": "copy comments", "type": "boolean" } }, "required": [ "destination_type" ] } }, "required": [ "move_zone" ] }, "InsertTemplateIntoZone": { "type": "object", "properties": { "template_id": { "pattern": "^[0-9]+$", "description": "Template asset global id to insert", "type": "string", "maxLength": 50 }, "placement": { "description": "Placement mode: AUTO, AT_POSITION, or NEAR_POSITION", "type": "string", "maxLength": 30, "enum": [ "AUTO", "AT_POSITION", "NEAR_POSITION" ] }, "position": { "description": "Required for AT_POSITION and NEAR_POSITION", "type": "object", "properties": { "top": { "description": "Top coordinate in zone space", "type": "number" }, "left": { "description": "Left coordinate in zone space", "type": "number" } } } }, "required": [ "template_id" ] }, "UpdateZoneStateRequest": { "type": "object", "properties": { "zone_state": { "description": "zone state. Allowed values: RESTORE, TRASH, DELETE (required)", "type": "string", "enum": [ "RESTORE", "TRASH", "DELETE" ] } }, "required": [ "zone_state" ] }, "ShareZonesWithMembersRequest": { "type": "object", "properties": { "members_info": { "minItems": 1, "maxItems": 100, "description": "members info. Max length: 11000 (required)", "type": "array", "items": { "type": "object", "properties": { "member_id": { "description": "member id. Max length: 100 (required)", "type": "string", "maxLength": 100 }, "member_type": { "description": "member type. Allowed values: USER, TEAM, ORG. Max length: 100 (required)", "type": "string", "maxLength": 100, "enum": [ "USER", "TEAM", "ORG" ] }, "role": { "description": "role. Allowed values: EDITOR, COMMENTER, VIEWER, ORGANISER", "type": "string", "enum": [ "EDITOR", "COMMENTER", "VIEWER", "ORGANISER" ] }, "resource_id": { "pattern": "^[a-f0-9A-F]{8}-[a-f0-9A-F]{4}-[a-f0-9A-F]{4}-[a-f0-9A-F]{4}-[a-f0-9A-F]{12}$", "description": "resource id (required)", "type": "string" }, "permission": { "description": "permission. Allowed values: restricted, allowed", "type": "string", "enum": [ "restricted", "allowed" ] } }, "required": [ "member_id", "member_type", "resource_id" ] } } }, "required": [ "members_info" ] } }, "responses": { "RateLimitExceededThisOperationAllows30Re": { "description": "Rate limit exceeded - this operation allows 30 requests per minute per user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } }, "SuccessfulResponse": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" } } } }, "InvalidRequestValidationFailed": { "description": "Invalid request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } }, "RateLimitExceededThisOperationAllows60Re": { "description": "Rate limit exceeded - this operation allows 60 requests per minute per user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } }, "NotFoundAResourceNamedInThePathDoesNotEx10": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } }, "InternalServerErrorTheRequestWasWellForm": { "description": "Internal server error - the request was well-formed but could not be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } }, "UnauthorizedMissingOrInvalidAccessToken9": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" } } } } }, "securitySchemes": { "vani-api-key": { "in": "header", "name": "x-vani-apikey", "description": "Edition-scoped API key. ACCEPTED, NOT YET REQUIRED: the bearer token alone authorises every operation today, which is why each one lists a token-only alternative first and a token-plus-key alternative second. Sending the key is harmless and forward-compatible -- the server reads it, and the requirement is expected to become mandatory, at which point the token-only alternative disappears from this contract. The key never authorises on its own. Read or create your edition's key from the edition settings. The two operations on the /editions collection itself never carry one: a key belongs to an edition, so the calls that list or create editions cannot present it.", "type": "apiKey" }, "iam-oauth2-schema": { "flows": { "authorizationCode": { "tokenUrl": "https://accounts.zoho.com/oauth/v2/token", "authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth", "scopes": { "Vani.teams.UPDATE": "Update team memberships, roles, and collaboration settings", "Vani.spaces.UPDATE": "Update workspaces, folders, and organizational settings", "Vani.spaces.DELETE": "Delete workspaces and folders", "Vani.zones.READ": "Read zones including tables, cells, and paragraph content", "Vani.editions.UPDATE": "Update existing document editions, modify version metadata and publishing state", "Vani.spaces.CREATE": "Create new workspaces, folders, and organizational structure", "Vani.teams.CREATE": "Create new teams and assign team memberships", "Vani.spaces.READ": "Read workspaces, folders, and organizational structure", "Vani.editions.CREATE": "Create new document editions and version snapshots", "Vani.zones.CREATE": "Create zones including tables, cells, and paragraph content", "Vani.teams.READ": "Read team memberships, roles, and collaboration settings", "Vani.editions.READ": "Read document editions, version history, and edition metadata", "Vani.teams.DELETE": "Delete teams and remove team memberships" } } }, "x-vani-data-centre": "com", "description": "OAuth 2.0 through Zoho Accounts for the .com data centre (the default). Authorisation is NOT served by the API server -- it is a separate host, and each data centre has its own. If your edition is on another data centre, keep these paths and substitute its host from x-vani-accounts-hosts on this scheme. An OAuth client is valid only in the data centre it was registered in, so register at that data centre's api-console. Note that the accounts host does not simply mirror the API host's TLD: Canada authorises at accounts.zohocloud.ca.", "x-vani-accounts-hosts": { "com": "accounts.zoho.com", "eu": "accounts.zoho.eu", "ae": "accounts.zoho.ae", "in": "accounts.zoho.in", "ca": "accounts.zohocloud.ca", "sa": "accounts.zoho.sa", "com.au": "accounts.zoho.com.au" }, "type": "oauth2" } }, "parameters": { "MemberId": { "schema": { "type": "string" }, "in": "path", "name": "member_id", "description": "The unique identifier of the member", "required": true }, "ZoneId": { "schema": { "type": "string" }, "in": "path", "name": "zone_id", "description": "The unique identifier of the zone", "required": true }, "SpaceId": { "schema": { "type": "string" }, "in": "path", "name": "space_id", "description": "The unique identifier of the space", "required": true }, "EditionId": { "schema": { "type": "string" }, "in": "path", "name": "edition_id", "description": "The unique identifier of the edition", "required": true }, "From": { "schema": { "pattern": "^[0-9]{1,6}$", "type": "string", "maxLength": 6 }, "in": "query", "name": "from", "description": "The starting index from where the results should be fetched. Default value is 0", "required": false }, "Limit": { "schema": { "pattern": "^[1-9][0-9]{0,2}$", "type": "string", "maxLength": 3 }, "in": "query", "name": "limit", "description": "The maximum number of results to return in the response. Default value is 20", "required": false } } }, "servers": [ { "variables": { "dc": { "default": "com", "description": "Data-centre TLD for your edition.", "enum": [ "com", "in", "eu", "ca", "com.au", "sa", "ae" ] } }, "description": "Vani API server. Select the data centre your edition is hosted in.", "url": "https://api.app.vanihq.{dc}" } ], "openapi": "3.1.0", "paths": { "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/move": { "post": { "summary": "Move a zone to another space", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveZoneRequest" } } } }, "operationId": "moveZone", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Zone Moved to a New Space": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:42:20", "last_modified_time": "Mon, 10 Mar 2025, 10:42:20", "is_favorite": "false", "space_name": "Project proposal", "publish": "false", "owner_zuid": "96384499", "can_edit": "true", "allow_embed": "false", "team_id": "693000000435005", "space_id": "693000000569361", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/4a971774-9ea7-4f1b-94c8-7199a254d6ba/move", "status": "success" } }, "Zone Moved to a New Space with Comments": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:42:20", "last_modified_time": "Mon, 10 Mar 2025, 10:42:20", "is_favorite": "false", "space_name": "Project proposal", "publish": "false", "owner_zuid": "96384499", "can_edit": "true", "allow_embed": "false", "team_id": "693000000435005", "space_id": "693000000569361", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/4a971774-9ea7-4f1b-94c8-7199a254d6ba/move", "status": "success" } }, "Zone Moved to an Existing Space with All Versions": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:30:38", "last_modified_time": "Mon, 10 Mar 2025, 10:32:00", "space_name": "MOVE", "publish": "false", "owner_zuid": "96384499", "team_id": "693000000435005", "allow_embed": "false", "space_id": "693000000569219", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/b313272b-fa45-4111-b61d-de64a0044260/move", "status": "success" } }, "Zone Moved to an Existing Space": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:30:38", "last_modified_time": "Mon, 10 Mar 2025, 10:32:00", "space_name": "MOVE", "publish": "false", "owner_zuid": "96384499", "team_id": "693000000435005", "allow_embed": "false", "space_id": "693000000569219", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/b313272b-fa45-4111-b61d-de64a0044260/move", "status": "success" } }, "Zone Moved to an Existing Space with Comments": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:30:38", "last_modified_time": "Mon, 10 Mar 2025, 10:32:00", "space_name": "MOVE", "publish": "false", "owner_zuid": "96384499", "team_id": "693000000435005", "allow_embed": "false", "space_id": "693000000569219", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/b313272b-fa45-4111-b61d-de64a0044260/move", "status": "success" } }, "Zone Moved to a New Space with All Versions": { "value": { "data": { "space_info": { "created_time": "Mon, 10 Mar 2025, 10:42:20", "last_modified_time": "Mon, 10 Mar 2025, 10:42:20", "is_favorite": "false", "space_name": "Project proposal", "publish": "false", "owner_zuid": "96384499", "can_edit": "true", "allow_embed": "false", "team_id": "693000000435005", "space_id": "693000000569361", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone moved successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/4a971774-9ea7-4f1b-94c8-7199a254d6ba/move", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized to Move Zone to an Existing Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "693000000481013" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000481013/zones/61fae7ca-ebcc-4ab9-881c-07b1aa9c814b/move", "status": "error" } }, "Unauthorized to Move Zone to a New Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "69300000569005" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/69300000569005/zones/4a971774-9ea7-4f1b-94c8-7199a254d6ba/move", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Target Space Not Found": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "S1009", "message": "Space not found", "space_id": "69300000569005" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/69300000569005/zones/b313272b-fa45-4111-b61d-de64a0044260/move", "status": "error" } }, "Zone Not Found 2": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "693000000569005" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000569005/zones/F2897959-A91F-4EB8-BE6B-E69411DC83F6/move", "status": "error" } }, "Zone Not Found": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "693000000562766" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562766/zones/0c77700c-35ef-4614-aad1-b4532d8e0bd3/move", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "CREATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/members": { "post": { "summary": "Share zones in a space with members", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareZonesWithMembersRequest" } } } }, "operationId": "shareZonesWithMembers", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Success": { "value": { "data": { "added_members": [ { "member_id": "3009000000002003", "access_state": "PARTIAL ACCESS", "resources": [ { "member_type": "TEAM", "added_time": "Tue, 08 Jul 2025, 01:58:52", "added_by": "96384499", "resource_type": "document", "resource_id": "6800EB6E-ED24-4EA6-91C6-805445418B17", "permission": "restricted" } ] }, { "member_id": "62609972", "access_state": "PARTIAL ACCESS", "resources": [ { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:16:32", "added_by": "80215739", "resource_type": "document", "resource_id": "6800EB6E-ED24-4EA6-91C6-805445418B17", "permission": "restricted" } ] } ] }, "message": "Resource members added successfully", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "success" } } } } } }, "206": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Partial Success": { "value": { "data": { "failed_members": [ { "error_message": "Resource member present", "error_code": "S1042", "zuid": "3009000000002003" } ], "added_members": [ { "member_id": "85572741", "access_state": "PARTIAL ACCESS", "resources": [ { "member_type": "USER", "added_time": "Wed, 09 Jul 2025, 15:52:18", "added_by": "96384499", "resource_type": "document", "resource_id": "d7ccf816-8293-4a2f-ae83-f10c0e3a6645", "permission": "restricted" } ] } ] }, "message": "Partial success: Some resource members added, others failed.", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "success" } } } } } }, "400": { "description": "Invalid request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Resource Member Present": { "value": { "error": { "details": { "failed_members": [ { "error_message": "Resource member present", "error_code": "S1042", "zuid": "3009000000002003" }, { "error_message": "Resource member present", "error_code": "S1042", "zuid": "3009000000002003" } ], "error_code": "R1002", "message": "Resource member add failed" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "error" } }, "Cannot Restrict The Owner": { "value": { "error": { "details": { "failed_members": [ { "error_message": "Cannot restrict owner role", "error_code": "S1034", "zuid": "80215739" } ], "error_code": "R1002", "message": "Resource member add failed" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "error" } }, "Cannot Restrict Non-Space Member": { "value": { "error": { "details": { "failed_members": [ { "error_message": "Cannot restrict non-project member", "error_code": "S1041", "zuid": "300900000000203" } ], "error_code": "R1002", "message": "Resource member add failed" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "error" } }, "Cannot Update Own Role": { "value": { "error": { "details": { "failed_members": [ { "error_message": "Cannot update own role", "error_code": "S1036", "zuid": "96384499" } ], "error_code": "R1002", "message": "Resource member add failed" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members", "status": "error" } } } } } }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "3009000000607005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000607005/zones/members", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Space Not found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1009", "message": "Space not found", "space_id": "300900000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/300900000618005/zones/members", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "CREATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Conditional Sharing" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones": { "post": { "summary": "Create a new zone", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZoneRequest" } } } }, "operationId": "createZone", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Success": { "value": { "data": { "zone_info": { "created_time": "Fri, 25 Jul 2025, 06:01:52", "zone_id": "ee01ded6-158e-4729-99b0-257ab23be6d1", "last_modified_time": "Fri, 25 Jul 2025, 06:01:52", "zone_name": "Zone 2", "space_id": "4855000000088149", "last_author_zuid": "888015717", "author_zuid": "888015717", "status": "ACTIVE" } }, "message": "Zone created successfully.", "request_uri": "/vani/api/v1/editions/888012145/spaces/4855000000088149/zones", "status": "success" } }, "Success: Zone Created Using Template": { "value": { "data": { "zone_info": { "created_time": "Fri, 25 Jul 2025, 06:02:20", "zone_id": "2bf37964-c959-4e3f-a4ac-ea09e607fb07", "last_modified_time": "Fri, 25 Jul 2025, 06:02:20", "zone_name": "Zone with template", "space_id": "4855000000088149", "last_author_zuid": "888015717", "author_zuid": "888015717", "status": "ACTIVE" } }, "message": "Zone created successfully.", "request_uri": "/vani/api/v1/editions/888012145/spaces/4855000000088149/zones", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "300900000005397" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/300900000005397/zones", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Template Not Found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1030", "message": "Template not found", "space_id": "3009000000419047" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000419047/zones", "status": "error" } } } } } }, "409": { "description": "Conflict - the requested change conflicts with the current resource state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Maximum Zone Limit Reached": { "value": { "error": { "details": { "edition_id": "85572652", "current_user_id": "96384499", "error_code": "Z1010", "message": "Zone creation limit reached", "space_id": "1600000000657005" } }, "request_uri": "/vani/api/v1/editions/85572652/spaces/1600000000657005/zones", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "CREATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/meta": { "get": { "summary": "Get zone metadata", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "operationId": "getZoneMeta", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Success": { "value": { "data": { "zone_info": { "created_time": "Tue, 15 Jul 2025, 10:49:13", "zone_id": "c606cdb1-ae46-47a6-847b-0a36caf9f797", "last_modified_time": "Tue, 29 Jul 2025, 13:46:46", "zone_key": "3009000000701095", "zone_name": "Zone 1", "space_id": "3009000000701079", "author_zuid": "96384499", "last_author_zuid": "96384499", "status": "ACTIVE" } }, "message": "Zone metadata fetched successfully.", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000701079/zones/c606cdb1-ae46-47a6-847b-0a36caf9f797/meta", "status": "success" } } } } } }, "400": { "description": "Invalid request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Zone Inactive": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "Z1011", "message": "Zone is not in an active state", "space_id": "3009000000789069" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000789069/zones/e42f51ec-e4dc-4dc5-9587-7a2e49dcdc2e/meta", "status": "error" } } } } } }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "3009000000789069" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000789069/zones/e42f51ec-e4dc-4dc5-9587-7a2e49dcdc2e/meta", "status": "error" } } } } } }, "403": { "description": "Forbidden - the caller is authenticated but not allowed to perform this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Restricted Zone": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1033", "message": "Restricted zone", "space_id": "3009000000789069" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000789069/zones/e42f51ec-e4dc-4dc5-9587-7a2e49dcdc2e/meta", "status": "error" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundAResourceNamedInThePathDoesNotEx10" }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] }, "put": { "summary": "Update zone metadata", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.UPDATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.UPDATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateZoneMetaRequest" } } } }, "operationId": "updateZoneMeta", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Success": { "value": { "data": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "current_user_id": "96384499", "space_id": "1505000000022005", "new_name": "Budget Report" }, "message": "Zone name updated successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/meta", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "zone_id": "a5fcca17-e9dd-414f-850d-0b920645b05d", "edition_id": "98723605", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "5265000000003011" } }, "request_uri": "/vani/api/v1/editions/98723605/spaces/5265000000003011/zones/a5fcca17-e9dd-414f-850d-0b920645b05d/meta", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Failure: Zone Not Found": { "value": { "error": { "details": { "zone_id": "198356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/198356E6-5F86-45FA-A7D5-ED8BB6D40DAE/meta", "status": "error" } } } } } }, "409": { "description": "Conflict - the requested change conflicts with the current resource state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Failure: New Zone Name Is Same as the Current Name": { "value": { "error": { "details": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "current_user_id": "96384499", "error_code": "Z1001", "message": "Zone name is same as the new name", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/meta", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "UPDATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/templates": { "post": { "summary": "Insert a template into a zone", "security": [ { "iam-oauth2-schema": [ "Vani.zones.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.zones.CREATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertTemplateIntoZone" } } } }, "operationId": "insertTemplateIntoZone", "responses": { "200": { "$ref": "#/components/responses/SuccessfulResponse" }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "$ref": "#/components/responses/UnauthorizedMissingOrInvalidAccessToken9" }, "404": { "$ref": "#/components/responses/NotFoundAResourceNamedInThePathDoesNotEx10" }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows60Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "UPDATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/state": { "put": { "summary": "Update zone state", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.UPDATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.UPDATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateZoneStateRequest" } } } }, "operationId": "updateZoneState", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Success 2": { "value": { "data": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "space_state": "TRASH", "current_user_id": "96384499", "space_id": "1505000000022005" }, "message": "Zone state updated successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/state", "status": "success" } }, "Success": { "value": { "data": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "space_state": "RESTORE", "current_user_id": "96384499", "space_id": "1505000000022005" }, "message": "Zone state updated successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/state", "status": "success" } } } } } }, "400": { "description": "Invalid request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Failure: Zone Threshold Violation": { "value": { "error": { "details": { "zone_id": "6F961124-4598-47D6-9BDA-1705DFBA07D7", "edition_id": "97375109", "current_user_id": "96384499", "error_code": "Z1009", "message": "Zone threshold violation", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/6F961124-4598-47D6-9BDA-1705DFBA07D7/state", "status": "error" } }, "Failure: Zone Is Already Trashed or Deleted": { "value": { "error": { "details": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "current_user_id": "96384499", "error_code": "Z1005", "message": "Zone is already trashed or deleted", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/state", "status": "error" } }, "Failure": { "value": { "error": { "details": { "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "current_user_id": "96384499", "error_code": "Z1006", "message": "Zone is deleted or already restored", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/state", "status": "error" } } } } } }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized 2": { "value": { "error": { "details": { "zone_id": "05A61516-A352-44C6-94C3-BE44F728C9D9", "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "300900000009397" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/300900000009397/zones/05A61516-A352-44C6-94C3-BE44F728C9D9/state", "status": "error" } }, "Unauthorized": { "value": { "error": { "details": { "zone_id": "05A61516-A352-44C6-94C3-BE44F728C9D9", "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "300900000005397" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/300900000005397/zones/05A61516-A352-44C6-94C3-BE44F728C9D9/state", "status": "error" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundAResourceNamedInThePathDoesNotEx10" }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "UPDATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/version": { "get": { "summary": "Get the current version of a zone", "security": [ { "iam-oauth2-schema": [ "Vani.zones.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.zones.READ" ] } ], "operationId": "getZoneVersion", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Using Filter Fields": { "value": { "data": { "zone_versions": { "restricted_versions": [ { "modified_by": "80215739", "version_id": "1373000000529563" } ], "allowed_versions": [] } }, "message": "Zone versions fetched successfully", "request_uri": "/vani/api/v1/editions/80585907/spaces/1373000000529203/zones/1b28dc96-a3bc-45c3-9977-e4089b513a31/version", "status": "success" } }, "Using from and limit Parameters": { "value": { "data": { "zone_versions": { "restricted_versions": [], "allowed_versions": [ { "modified_by": "80215739", "version_id": "149000043835113" } ] } }, "message": "Zone versions fetched successfully", "request_uri": "/vani/api/v1/editions/75434908/spaces/149000042348078/zones/89cf903a-0701-41b3-823c-f2229436333e/version", "status": "success" } }, "Using fromDate Parameter": { "value": { "data": { "zone_versions": { "restricted_versions": [], "allowed_versions": [ { "version_time": "Fri, 24 Jan 2025, 11:55:53", "modified_by": "80215739", "description": "", "version_id": "149000043835113" } ] } }, "message": "Zone versions fetched successfully", "request_uri": "/vani/api/v1/editions/75434908/spaces/149000042348078/zones/89cf903a-0701-41b3-823c-f2229436333e/version", "status": "success" } }, "Success": { "value": { "data": { "zone_versions": { "restricted_versions": [ { "version_time": "Tue, 04 Feb 2025, 12:58:24", "modified_by": "96384499", "description": "activated", "version_id": "1600000000657036" } ], "allowed_versions": [ { "version_time": "Sun, 16 Feb 2025, 03:09:13", "modified_by": "96384499", "description": "", "version_id": "1505000000099005" }, { "version_time": "Sun, 16 Feb 2025, 03:08:50", "modified_by": "96384499", "description": "activated", "version_id": "1505000000097249" } ] } }, "message": "Zone versions fetched successfully", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/DBB83581-F98F-4120-9431-FDC16515FE00/version", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "85572652", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "160000000657005" } }, "request_uri": "/vani/api/v1/editions/85572652/spaces/160000000657005/zones/ef7b7fe1-327b-4ec1-904d-8232677d689c/version", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Zone Not Found": { "value": { "error": { "details": { "edition_id": "75434908", "current_user_id": "80215739", "error_code": "Z1008", "message": "Zone not found", "space_id": "149000042348078" } }, "request_uri": "/vani/api/v1/editions/75434908/spaces/149000042348078/zones/89cf103a-0701-41b3-823c-f2229436333e/version", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows60Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "type": "string", "maxLength": 1000, "enum": [ "modified_by", "version_id", "version_time", "description", "uri" ] }, "in": "query", "name": "fields", "description": "Specifies the fields (comma-separated) to retrieve. Allowed values: modified_by, version_id, version_time, description, uri", "required": false }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/Limit" }, { "schema": { "type": "string" }, "in": "query", "name": "from_date", "description": "Allows you to fetch only those Zone versions that have been created or modified since the given timestamp", "required": false } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Zone Versions" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/meta": { "get": { "summary": "Get metadata for all zones in a space", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "operationId": "getSpaceZonesMeta", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Using Filter Fields": { "value": { "data": { "zones_info": { "zone_order": [ "0e1e3a8a-a115-463e-bdb6-f540ab37eeb6", "6F961124-4598-47D6-9BDA-1705DFBA07D7", "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE" ], "zone_meta": { "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE": { "created_time": "Tue, 04 Feb 2025, 11:34:28", "zone_name": "Zone 3" }, "0e1e3a8a-a115-463e-bdb6-f540ab37eeb6": { "created_time": "Tue, 28 Jan 2025, 11:59:50", "zone_name": "Zone 1" }, "6F961124-4598-47D6-9BDA-1705DFBA07D7": { "created_time": "Tue, 04 Feb 2025, 11:34:26", "zone_name": "Zone 2" } } } }, "message": "Zone metadata fetched successfully.", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000095397/zones/meta", "status": "success" } }, "Success": { "value": { "data": { "zones_info": { "zone_order": [ "0e1e3a8a-a115-463e-bdb6-f540ab37eeb6", "6F961124-4598-47D6-9BDA-1705DFBA07D7", "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE" ], "zone_meta": { "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE": { "created_time": "Tue, 04 Feb 2025, 11:34:28", "last_modified_time": "Tue, 04 Feb 2025, 11:34:39", "zone_name": "Zone 3", "space_id": "1505000000022005", "author_zuid": "96384499", "last_author_zuid": "96384499", "status": "ACTIVE" }, "0e1e3a8a-a115-463e-bdb6-f540ab37eeb6": { "created_time": "Tue, 28 Jan 2025, 11:59:50", "last_modified_time": "Tue, 28 Jan 2025, 19:34:28", "zone_name": "Zone 1", "space_id": "1505000000022005", "author_zuid": "96384499", "last_author_zuid": "96384499", "status": "ACTIVE" }, "6F961124-4598-47D6-9BDA-1705DFBA07D7": { "created_time": "Tue, 04 Feb 2025, 11:34:26", "last_modified_time": "Tue, 04 Feb 2025, 11:34:35", "zone_name": "Zone 2", "space_id": "1505000000022005", "author_zuid": "96384499", "last_author_zuid": "96384499", "status": "ACTIVE" } } } }, "message": "Zone metadata fetched successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/meta", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "97375109", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "1505000000022005" } }, "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/meta", "status": "error" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundAResourceNamedInThePathDoesNotEx10" }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows60Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "schema": { "type": "string", "maxLength": 1000, "enum": [ "created_time", "last_modified_time", "zone_name", "author_zuid", "status", "last_author_zuid", "space_id", "state_modified_time" ] }, "in": "query", "name": "fields", "description": "Specifies the fields (comma-separated) to retrieve. Allowed values: created_time, last_modified_time, zone_name, author_zuid, status, last_author_zuid, space_id, state_modified_time", "required": false } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/duplicate": { "post": { "summary": "Duplicate a zone", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateZoneRequest" } } } }, "operationId": "duplicateZone", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "NEW SPACE - with comments": { "value": { "data": { "space_id": "693000000598369", "uri": "/vani/api/v1/editions/75918186/spaces/693000000598369/zones/meta" }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated in the Same Space with Comments": { "value": { "data": { "zone_id": "f721081a-6208-4058-95a5-fe4d787db67d", "space_id": 693000000562161 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated into a New Space": { "value": { "data": { "space_id": "693000000598369", "uri": "/vani/api/v1/editions/75918186/spaces/693000000598369/zones/meta" }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated into a New Space with Space Name": { "value": { "data": { "space_id": "693000000598439", "uri": "/vani/api/v1/editions/75918186/spaces/693000000598439/zones/meta" }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated in the Same Space with Members": { "value": { "data": { "zone_id": "f721081a-6208-4058-95a5-fe4d787db67d", "space_id": 693000000562161 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated in the Same Space with All Versions": { "value": { "data": { "zone_id": "f721081a-6208-4058-95a5-fe4d787db67d", "space_id": 693000000562161 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated in an Existing Space with All Versions": { "value": { "data": { "zone_id": "64d56703-7071-4670-8153-33819171239f", "space_id": 693000000562297 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated in an Existing Space": { "value": { "data": { "zone_id": "64d56703-7071-4670-8153-33819171239f", "space_id": 693000000562297 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated in an Existing Space with a New Zone Name": { "value": { "data": { "zone_id": "9a853213-9f1a-488d-bbcf-9efcb3e2d419", "space_id": 693000000562297 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated in an Existing Space Using Version ID": { "value": { "data": { "zone_id": "ea5e020b-4e3b-4e5d-8229-b38c5f8a3084", "space_id": 693000000562297 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated into a New Space Using Version ID": { "value": { "data": { "space_id": "693000000603451", "uri": "/vani/api/v1/editions/75918186/spaces/693000000603451/zones/meta" }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated in an Existing Space with Comments": { "value": { "data": { "zone_id": "64d56703-7071-4670-8153-33819171239f", "space_id": 693000000562297 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "success" } }, "Zone Duplicated in the Same Space": { "value": { "data": { "zone_id": "f721081a-6208-4058-95a5-fe4d787db67d", "space_id": 693000000562161 }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } }, "Zone Duplicated into a New Space with All Versions": { "value": { "data": { "space_id": "693000000598369", "uri": "/vani/api/v1/editions/75918186/spaces/693000000598369/zones/meta" }, "message": "Zone duplicated successfully", "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1a-4ef9-8f25-75a873ff7f10/duplicate", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized to Duplicate Zone in an Existing Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "69300000562248" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/69300000562248/zones/91c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "error" } }, "Unauthorized to Duplicate Zone in the Same Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "693000000481013" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000481013/zones/61fae7ca-ebcc-4ab9-881c-07b1aa9c814b/duplicate", "status": "error" } }, "Unauthorized to Duplicate Zone into a New Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "69300000562248" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/69300000562248/zones/91c26165-0165-4b48-b976-16c924498a8c/duplicate", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Zone Not Found in the Existing Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "693000000562248" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562248/zones/11c26965-0165-4b48-b976-16c924498a8c/duplicate", "status": "error" } }, "Zone Not Found in the Same Space": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "693000000562161" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000562161/zones/8915a5e7-ba1b-4ef9-8f25-75a873ff7f10/duplicate", "status": "error" } }, "Zone Not Found": { "value": { "error": { "details": { "edition_id": "75918186", "current_user_id": "96384499", "error_code": "Z1008", "message": "Zone not found", "space_id": "693000000599045" } }, "request_uri": "/vani/api/v1/editions/75918186/spaces/693000000599045/zones/2da6aa5e-8a20-4d6a-9551-e97fc4b2bd9f/duplicate", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "CREATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Zones" ] } }, "/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/members/{member_id}": { "post": { "summary": "Share every zone in a space with a member", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.CREATE" ] } ], "operationId": "shareAllZonesWithMember", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Shared with Team": { "value": { "data": { "space_resource_info": { "member_id": "3009000000002003", "access_state": "FULL ACCESS", "resources": [ { "member_type": "TEAM", "added_time": "Mon, 07 Jul 2025, 18:22:20", "added_by": "80215739", "resource_type": "document", "resource_id": "d7ccf816-8293-4a2f-ae83-f10c0e3a6645", "permission": "allowed" }, { "member_type": "TEAM", "added_time": "Mon, 07 Jul 2025, 18:22:20", "added_by": "80215739", "resource_type": "document", "resource_id": "31E57A34-3405-41D2-A2B6-7BAACAE9EE02", "permission": "allowed" }, { "member_type": "TEAM", "added_time": "Mon, 07 Jul 2025, 18:22:20", "added_by": "80215739", "resource_type": "document", "resource_id": "9E23791B-B3AE-4877-9119-3F636DC685AC", "permission": "allowed" }, { "member_type": "TEAM", "added_time": "Mon, 07 Jul 2025, 18:22:08", "added_by": "80215739", "resource_type": "document", "resource_id": "6800EB6E-ED24-4EA6-91C6-805445418B17", "permission": "allowed" } ], "space_id": "3009000000618005" } }, "message": "All resources shared successfully", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/3009000000002003", "status": "success" } }, "Shared with Member": { "value": { "data": { "space_resource_info": { "member_id": "62609972", "access_state": "FULL ACCESS", "resources": [ { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:13:11", "added_by": "80215739", "resource_type": "document", "resource_id": "d7ccf816-8293-4a2f-ae83-f10c0e3a6645", "permission": "allowed" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:16:32", "added_by": "80215739", "resource_type": "document", "resource_id": "6800EB6E-ED24-4EA6-91C6-805445418B17", "permission": "allowed" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:16:32", "added_by": "80215739", "resource_type": "document", "resource_id": "31E57A34-3405-41D2-A2B6-7BAACAE9EE02", "permission": "allowed" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:13:11", "added_by": "80215739", "resource_type": "document", "resource_id": "9E23791B-B3AE-4877-9119-3F636DC685AC", "permission": "allowed" } ], "space_id": "3009000000618005" } }, "message": "All resources shared successfully", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/62609972", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "3009000000612023" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000612023/zones/members/3009000000002004", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Member Not Found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1015", "message": "member is not part of the Space", "space_id": "3009000000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/3009000000002004", "status": "error" } }, "Space Not Found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1009", "message": "Space not found", "space_id": "300900000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/300900000618005/zones/members/3009000000002004", "status": "error" } } } } } }, "409": { "description": "Conflict - the requested change conflicts with the current resource state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Member Already Has Full Access": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1045", "message": "Member already has full access", "space_id": "3009000000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/3009000000002003", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows30Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "CREATE", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/MemberId" } ], "x-vani-read-only": false, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 30 }, "tags": [ "Conditional Sharing" ] }, "get": { "summary": "Get the zones in a space shared with a member", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "operationId": "getZonesSharedWithMember", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniEnvelope" }, "examples": { "Get Member Resources – Full Access": { "value": { "data": { "space_resource_info": { "member_id": "96384499", "access_state": "FULL ACCESS", "resources": [], "space_id": "3009000000618005" } }, "message": "User resources fetched successfully.", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/96384499", "status": "success" } }, "Get Member Resources – Partial Access": { "value": { "data": { "space_resource_info": { "member_id": "62609972", "access_state": "PARTIAL ACCESS", "resources": [ { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:13:11", "added_by": "80215739", "resource_type": "document", "resource_id": "9E23791B-B3AE-4877-9119-3F636DC685AC", "permission": "restricted" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:13:11", "added_by": "80215739", "resource_type": "document", "resource_id": "d7ccf816-8293-4a2f-ae83-f10c0e3a6645", "permission": "allowed" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:16:32", "added_by": "80215739", "resource_type": "document", "resource_id": "6800EB6E-ED24-4EA6-91C6-805445418B17", "permission": "allowed" }, { "member_type": "USER", "added_time": "Mon, 07 Jul 2025, 18:16:32", "added_by": "80215739", "resource_type": "document", "resource_id": "31E57A34-3405-41D2-A2B6-7BAACAE9EE02", "permission": "allowed" } ], "space_id": "3009000000618005" } }, "message": "User resources fetched successfully.", "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/62609972", "status": "success" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestValidationFailed" }, "401": { "description": "Unauthorized - missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Unauthorized": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "A1003", "message": "The user doesn't have permission to perform this action", "space_id": "3009000000612023" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000612023/zones/members/9638449", "status": "error" } } } } } }, "404": { "description": "Not found - a resource named in the path does not exist, or is not visible to the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaniError" }, "examples": { "Member Not Found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1015", "message": "member is not part of the Space", "space_id": "3009000000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/3009000000618005/zones/members/9638449", "status": "error" } }, "Space Not Found": { "value": { "error": { "details": { "edition_id": "96499735", "current_user_id": "96384499", "error_code": "S1009", "message": "Space not found", "space_id": "009000000618005" } }, "request_uri": "/vani/api/v1/editions/96499735/spaces/009000000618005/zones/members/62609972", "status": "error" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitExceededThisOperationAllows60Re" }, "500": { "$ref": "#/components/responses/InternalServerErrorTheRequestWasWellForm" } }, "x-vani-operation-type": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/MemberId" } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Conditional Sharing" ] } } }, "info": { "contact": { "name": "Vani API Support", "url": "https://www.vanihq.com/resources/api/doc/" }, "description": "Zones (documents) within a space: lifecycle, metadata, versioning, and per-zone sharing.", "title": "Zones", "version": "1.0.0" }, "tags": [ { "name": "Zones", "description": "Create, duplicate, move, and update zones, read their metadata, and insert templates into them." }, { "name": "Zone Versions", "description": "Read the current version of a zone." }, { "name": "Conditional Sharing", "description": "Share individual zones within a space with a specific member." } ] }