{ "components": { "schemas": { "GetRelationEvidenceRequest": { "type": "object", "properties": { "relation_context": { "$ref": "#/components/schemas/RelationContext" }, "target_object": { "$ref": "#/components/schemas/ObjectRef" }, "source_object": { "$ref": "#/components/schemas/ObjectRef" }, "relation_types": { "type": "array", "items": { "$ref": "#/components/schemas/RelationType" } } }, "required": [ "source_object", "target_object" ] }, "GetTraversalIndexResponse": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/TraversalIndexResult" }, "error": { "$ref": "#/components/schemas/AgentError" }, "effective_scope": { "$ref": "#/components/schemas/ContainerScope" } } }, "GetObjectAncestorsRequest": { "type": "object", "properties": { "max_levels": { "format": "int32", "type": "string" }, "object": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "object" ] }, "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" ] }, "AgentErrorCode": { "type": "string", "enum": [ "AGENT_ERROR_CODE_UNSPECIFIED", "INVALID_ARGUMENT", "SPACE_NOT_FOUND", "ZONE_NOT_FOUND", "FRAME_NOT_FOUND", "OBJECT_NOT_FOUND", "NO_EMPTY_REGION", "NO_VISUAL_NEIGHBOR", "PLACEMENT_CONFLICT", "UNSUPPORTED_OPERATION", "INTERNAL_ERROR" ] }, "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" } } }, "RelationContext": { "type": "object", "properties": { "containment_context_type": { "$ref": "#/components/schemas/ContainmentContextType" } } }, "VisualDirection": { "type": "string", "enum": [ "VISUAL_DIRECTION_UNSPECIFIED", "UP", "DOWN", "LEFT", "RIGHT", "FRONT", "BACK" ] }, "GetTraversalSequenceRequest": { "type": "object", "properties": { "traversal_scope": { "$ref": "#/components/schemas/ContainerScope" }, "payload": { "$ref": "#/components/schemas/VaniTraversalSequencePayload" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "anchor" ] }, "GetObjectChildrenRequest": { "type": "object", "properties": { "object_types": { "type": "array", "items": { "$ref": "#/components/schemas/VaniObjectType" } }, "payload": { "$ref": "#/components/schemas/ChildrenPayload" }, "object": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "object" ] }, "GetTraversalIndexRequest": { "type": "object", "properties": { "traversal_scope": { "$ref": "#/components/schemas/ContainerScope" }, "payload": { "$ref": "#/components/schemas/VaniTraversalIndexPayload" }, "object": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "object" ] }, "FindRelatedObjectsRequest": { "type": "object", "properties": { "relation_context": { "$ref": "#/components/schemas/RelationContext" }, "relation_query": { "type": "string" }, "max_depth": { "format": "int32", "type": "string" }, "scope": { "$ref": "#/components/schemas/SpatialComputationScope" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" }, "relation_types": { "type": "array", "items": { "$ref": "#/components/schemas/RelationType" } }, "max_results": { "format": "int32", "type": "string" } }, "required": [ "anchor" ] }, "ObjectRef": { "type": "object", "properties": { "zone_id": { "type": "string" }, "object_id": { "type": "string" }, "frame_id": { "type": "string" } } }, "VaniTraversalFilter": { "type": "object", "properties": { "object_types": { "type": "array", "items": { "$ref": "#/components/schemas/VaniObjectType" } }, "include_hidden": { "type": "boolean" }, "include_locked": { "type": "boolean" } } }, "DescendantFlatSelection": { "type": "object", "x-vani-oneof-groups": [ { "members": [ "all", "range", "index_set" ], "name": "selector" } ], "properties": { "all": { "type": "boolean" }, "index_set": { "$ref": "#/components/schemas/IndexSet" }, "range": { "$ref": "#/components/schemas/IndexRange" } } }, "GetDistanceBetweenObjectsRequest": { "type": "object", "properties": { "target_object": { "$ref": "#/components/schemas/ObjectRef" }, "source_object": { "$ref": "#/components/schemas/ObjectRef" } } }, "ContainerScope_ScopeType": { "type": "string", "enum": [ "SCOPE_TYPE_UNSPECIFIED", "ZONE_ROOT", "FRAME_ROOT", "GROUP_ROOT" ] }, "ContainmentContextType": { "type": "string", "enum": [ "CONTAINMENT_CONTEXT_TYPE_UNSPECIFIED", "GROUP", "FRAME" ] }, "GetTraversalWindowResponse": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/GetTraversalWindowResult" }, "error": { "$ref": "#/components/schemas/AgentError" }, "effective_scope": { "$ref": "#/components/schemas/ContainerScope" } } }, "GetTraversalWindowResult": { "type": "object", "properties": { "before_objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectRef" } }, "after_objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectRef" } }, "meta": { "$ref": "#/components/schemas/TraversalWindowResult" } } }, "Bounds": { "type": "object", "properties": { "x": { "format": "float", "type": "string" }, "width": { "format": "float", "type": "string" }, "y": { "format": "float", "type": "string" }, "height": { "format": "float", "type": "string" } } }, "DescendantPathSelection": { "type": "object", "properties": { "patterns": { "type": "array", "items": { "$ref": "#/components/schemas/DescendantPathSelection_PathPattern" } } } }, "DescendantPathSelection_PathSegmentSelection": { "type": "object", "x-vani-oneof-groups": [ { "members": [ "index", "range", "index_set" ], "name": "selector" } ], "properties": { "index_set": { "$ref": "#/components/schemas/IndexSet" }, "index": { "format": "int32", "type": "string" }, "range": { "$ref": "#/components/schemas/IndexRange" } } }, "GetTraversalSequenceResponse": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/GetTraversalSequenceResult" }, "error": { "$ref": "#/components/schemas/AgentError" } } }, "IndexRange": { "type": "object", "properties": { "start_index": { "format": "int32", "type": "string" }, "end_index": { "format": "int32", "type": "string" } } }, "DescendantsPayload": { "type": "object", "x-vani-oneof-groups": [ { "members": [ "flat_selection", "path_selection" ], "name": "selection" } ], "properties": { "max_depth": { "format": "int32", "type": "string" }, "max_results": { "format": "int32", "type": "string" }, "flat_selection": { "$ref": "#/components/schemas/DescendantFlatSelection" }, "path_selection": { "$ref": "#/components/schemas/DescendantPathSelection" } } }, "GetConnectedObjectsRequest": { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/ConnectedObjectsPayload" }, "scope": { "$ref": "#/components/schemas/ContainerScope" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "anchor" ] }, "ChildrenPayload": { "type": "object", "x-vani-oneof-groups": [ { "members": [ "all", "range", "index_set" ], "name": "selection" } ], "properties": { "all": { "type": "boolean" }, "index_set": { "$ref": "#/components/schemas/IndexSet" }, "range": { "$ref": "#/components/schemas/IndexRange" }, "max_results": { "format": "int32", "type": "string" } } }, "SpatialComputationScope": { "type": "object", "x-vani-oneof-groups": [ { "members": [ "container_scope", "absolute_bounds", "percent_bounds" ], "name": "mode" } ], "properties": { "percent_bounds": { "$ref": "#/components/schemas/PercentBounds" }, "container_scope": { "$ref": "#/components/schemas/ContainerScope" }, "absolute_bounds": { "$ref": "#/components/schemas/Bounds" } } }, "GetTraversalSequenceResult": { "type": "object", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectRef" } } } }, "AgentError": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AgentErrorCode" }, "message": { "type": "string" } } }, "DescendantPathSelection_PathPattern": { "type": "object", "properties": { "segments": { "type": "array", "items": { "$ref": "#/components/schemas/DescendantPathSelection_PathSegmentSelection" } } } }, "TraversalDirection": { "type": "string", "enum": [ "TRAVERSAL_DIRECTION_UNSPECIFIED", "TRAVERSAL_DIRECTION_NEXT", "TRAVERSAL_DIRECTION_PREVIOUS" ] }, "GetTraversalWindowRequest": { "type": "object", "properties": { "traversal_scope": { "$ref": "#/components/schemas/ContainerScope" }, "payload": { "$ref": "#/components/schemas/VaniTraversalWindowPayload" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "anchor" ] }, "VaniObjectType": { "type": "string", "enum": [ "VANI_OBJECT_TYPE_UNSPECIFIED", "VANI_OBJECT_TYPE_SHAPE", "VANI_OBJECT_TYPE_CONNECTOR", "VANI_OBJECT_TYPE_PICTURE", "VANI_OBJECT_TYPE_GROUP_SHAPE", "VANI_OBJECT_TYPE_DOMAIN_DIAGRAM", "VANI_OBJECT_TYPE_DIAGRAM", "VANI_OBJECT_TYPE_STRUCTURE", "VANI_OBJECT_TYPE_STRUCTURE_MINDMAP", "VANI_OBJECT_TYPE_STRUCTURE_KANBAN", "VANI_OBJECT_TYPE_STRUCTURE_STACK", "VANI_OBJECT_TYPE_TABLE", "VANI_OBJECT_TYPE_CHART", "VANI_OBJECT_TYPE_DATABASE_TABLE", "VANI_OBJECT_TYPE_STICKY_NOTE" ] }, "TraversalWindowResult": { "type": "object", "properties": { "anchor_index_path": { "type": "array", "items": { "format": "int32", "type": "string" } } } }, "RelationType": { "type": "string", "enum": [ "RELATION_TYPE_UNSPECIFIED", "CONNECTED_BY_EDGE", "CO_CONTAINED", "SAME_STRUCTURE", "PARENT", "CHILD", "ANCESTOR", "DESCENDANT", "SIBLING" ] }, "GetVisualSequenceRequest": { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/VaniVisualSequencePayload" }, "scope": { "$ref": "#/components/schemas/SpatialComputationScope" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" } } }, "VaniTraversalWindowPayload": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VaniTraversalFilter" }, "after_count": { "format": "int32", "type": "string" }, "before_count": { "format": "int32", "type": "string" }, "wrap": { "type": "boolean" } } }, "GetObjectDescendantsRequest": { "type": "object", "properties": { "object_types": { "type": "array", "items": { "$ref": "#/components/schemas/VaniObjectType" } }, "payload": { "$ref": "#/components/schemas/DescendantsPayload" }, "object": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "object" ] }, "IndexSet": { "type": "object", "properties": { "indices": { "type": "array", "items": { "format": "int32", "type": "string" } } } }, "ContainerScope": { "type": "object", "properties": { "scope_type": { "$ref": "#/components/schemas/ContainerScope_ScopeType" } } }, "TraversalIndexResult": { "type": "object", "properties": { "index_path": { "type": "array", "items": { "format": "int32", "type": "string" } } } }, "VaniObjectsAroundPayload": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VaniVisualFilter" }, "max_results": { "format": "int32", "type": "string" } } }, "VaniTraversalSequencePayload": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VaniTraversalFilter" }, "max_results": { "format": "int32", "type": "string" }, "wrap": { "type": "boolean" }, "direction": { "$ref": "#/components/schemas/TraversalDirection" } } }, "VaniVisualFilter": { "type": "object", "properties": { "object_types": { "type": "array", "items": { "$ref": "#/components/schemas/VaniObjectType" } }, "include_hidden": { "type": "boolean" }, "include_locked": { "type": "boolean" } } }, "GetObjectParentsRequest": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/ObjectRef" } }, "required": [ "object" ] }, "VaniTraversalIndexPayload": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VaniTraversalFilter" } } }, "PercentBounds": { "type": "object", "properties": { "right_pct": { "format": "float", "type": "string" }, "top_pct": { "format": "float", "type": "string" }, "bottom_pct": { "format": "float", "type": "string" }, "left_pct": { "format": "float", "type": "string" } } }, "VaniVisualSequencePayload": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/VaniVisualFilter" }, "max_results": { "format": "int32", "type": "string" }, "wrap": { "type": "boolean" }, "direction": { "$ref": "#/components/schemas/VisualDirection" } } }, "GetObjectsAroundRequest": { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/VaniObjectsAroundPayload" }, "scope": { "$ref": "#/components/schemas/SpatialComputationScope" }, "anchor": { "$ref": "#/components/schemas/ObjectRef" } } }, "ConnectedObjectsPayload": { "type": "object", "properties": { "max_depth": { "format": "int32", "type": "string" }, "max_results": { "format": "int32", "type": "string" }, "direction": { "$ref": "#/components/schemas/ConnectionDirection" } } }, "ConnectionDirection": { "type": "string", "enum": [ "CONNECTION_DIRECTION_UNSPECIFIED", "CONNECTION_DIRECTION_ANY", "CONNECTION_DIRECTION_INCOMING", "CONNECTION_DIRECTION_OUTGOING", "CONNECTION_DIRECTION_UNDIRECTED" ] } }, "responses": { "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": { "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 } } }, "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": { "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/traversal/index": { "get": { "summary": "Get hierarchical index path of an object within the zone traversal order", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getTraversalIndex", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VaniEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetTraversalIndexResponse" } } } ] } } } }, "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetTraversalIndexRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetTraversalIndexRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "traversal_query", "description": "`traversal_query` — JSON-encoded GetTraversalIndex request: object, optional traversal_scope, optional payload (filter). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Traversal" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/visual-navigation/adjacent-elements": { "get": { "summary": "Get the elements adjacent to an anchor, with distance and direction", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getVisualNavigationAdjacentElements", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetObjectsAroundRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetObjectsAroundRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "nav_query", "description": "`nav_query` — JSON-encoded GetObjectsAround request: anchor, optional payload and scope. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Visual Navigation" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/find": { "get": { "summary": "Find related objects using deterministic relation filters and optional semantic hint", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipFind", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/FindRelatedObjectsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/FindRelatedObjectsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded FindRelatedObjects request: anchor, optional scope, relation_types, relation_context, relation_query, max_depth, max_results. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/traversal/sequence": { "get": { "summary": "Get ordered traversal neighbors from an anchor point in the zone", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getTraversalSequence", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VaniEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetTraversalSequenceResponse" } } } ] } } } }, "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetTraversalSequenceRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetTraversalSequenceRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "traversal_query", "description": "`traversal_query` — JSON-encoded GetTraversalSequence request: anchor, optional traversal_scope, optional payload (direction, filter, max_results, wrap). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Traversal" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/traversal/window": { "get": { "summary": "Get before/after context window around an anchor object in the zone", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getTraversalWindow", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VaniEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetTraversalWindowResponse" } } } ] } } } }, "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetTraversalWindowRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetTraversalWindowRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "traversal_query", "description": "`traversal_query` — JSON-encoded GetTraversalWindow request: anchor, optional traversal_scope, optional payload (filter, before_count, after_count, wrap). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Traversal" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/descendants": { "get": { "summary": "Get hierarchical descendants of a container via BFS traversal", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipDescendants", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetObjectDescendantsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetObjectDescendantsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetObjectDescendants request: object, optional object_types, optional payload (max_depth, max_results, flat_selection | path_selection). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/ancestors": { "get": { "summary": "Get ancestor chain for an object in the zone hierarchy", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipAncestors", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetObjectAncestorsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetObjectAncestorsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetObjectAncestors request: object, optional max_levels. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/children": { "get": { "summary": "List the immediate child objects of one container (frame, group or zone root), optionally filtered by object type and windowed by range or index set. One level only - use getRelationshipDescendants for the deeper subtree.", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipChildren", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetObjectChildrenRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetObjectChildrenRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetObjectChildren request: object, optional object_types, optional payload (all | range | index_set, max_results). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/visual-navigation/distance": { "get": { "summary": "Get the geometric distance between two objects", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getVisualNavigationDistance", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetDistanceBetweenObjectsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetDistanceBetweenObjectsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "nav_query", "description": "`nav_query` — JSON-encoded GetDistanceBetweenObjects request: source_object, target_object. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Visual Navigation" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/connected": { "get": { "summary": "Get objects connected to anchor through connector graph traversal", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipConnected", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetConnectedObjectsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetConnectedObjectsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetConnectedObjects request: anchor, optional scope (container root), optional payload (direction, max_depth, max_results). Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/parents": { "get": { "summary": "Get direct parent of an object in the zone hierarchy", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipParents", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetObjectParentsRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetObjectParentsRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetObjectParents request: object. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/relationships/evidence": { "get": { "summary": "Get deterministic relation evidence between two objects", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getRelationshipEvidence", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetRelationEvidenceRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetRelationEvidenceRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "relationship_query", "description": "`relationship_query` — JSON-encoded GetRelationEvidence request: source_object, target_object, optional relation_types and relation_context. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Relationships" ] } }, "/sdk/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/visual-navigation/sequence": { "get": { "summary": "Get the visually ordered neighbours of an anchor object", "security": [ { "iam-oauth2-schema": [ "Vani.spaces.READ" ] }, { "vani-api-key": [], "iam-oauth2-schema": [ "Vani.spaces.READ" ] } ], "x-vani-transitional": true, "operationId": "getVisualNavigationSequence", "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": "READ", "parameters": [ { "$ref": "#/components/parameters/EditionId" }, { "$ref": "#/components/parameters/SpaceId" }, { "$ref": "#/components/parameters/ZoneId" }, { "schema": { "contentSchema": { "$ref": "#/components/schemas/GetVisualSequenceRequest" }, "x-vani-schema": { "$ref": "#/components/schemas/GetVisualSequenceRequest" }, "contentMediaType": "application/json", "x-vani-stringified": true, "type": "string" }, "in": "query", "name": "nav_query", "description": "`nav_query` — JSON-encoded GetVisualSequence request: anchor, payload (direction/filter/limits), optional scope. Send this value as a JSON string, not as a JSON object — URL-encode the encoded JSON.", "required": true } ], "x-vani-read-only": true, "x-vani-destructive": false, "x-vani-throttle": { "duration": "1M", "threshold": 60 }, "tags": [ "Visual Navigation" ] } } }, "info": { "contact": { "name": "Vani API Support", "url": "https://www.vanihq.com/resources/api/doc/" }, "description": "Traverse the zone hierarchy, resolve relationships, and navigate visually between objects.", "title": "Navigation & Relationships", "version": "1.0.0" }, "tags": [ { "name": "Relationships", "description": "Resolve parents, children, ancestors, descendants, and connected objects." }, { "name": "Traversal", "description": "Walk the zone in index, sequence, and windowed order." }, { "name": "Visual Navigation", "description": "Find adjacent elements, geometric distances, and visual ordering." } ] }