Help Doc Access Vani

ZONES API

Manage resources and operations related to Zones.

GET Zone Meta & Zone Order

GET https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/meta
Required Scopes:
vani.spaces.read

Retrieves proto data for a specific Zone, typically used to access the Zone's structure and metadata.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.

Responses

200 success
200 using filter fields
401 unauthorized
success - Response
{ "data": { "zones_info": { "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" } }, "zone_order": [ "0e1e3a8a-a115-463e-bdb6-f540ab37eeb6", "6F961124-4598-47D6-9BDA-1705DFBA07D7", "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE" ] } }, "message": "Zone metadata fetched successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/meta", "status": "success" }

Code Examples

cURL Command line HTTP client
cURL
curl -X GET "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/meta" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json"

POST Create Zone

POST https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones
Required Scopes:
vani.spaces.create

Creates a new Zone within a specific Space in an edition.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
create_zone string body Based on Request A JSON object containing the zone_name parameter to define the new Zone's name.
zone_name string body Based on Request The name of the Zone to be created

Request Body

JSON
{ "create_zone": { "zone_name": "Zone 2" } }

Responses

200 success - json response
200 success - serialized response
200 success with template - json response
200 success with template - serialized response
409 zone limit reached
401 unauthorized
success - json response - Response
{ "data": "{\"space_data\":{\n \"id\": \"1303000000628003\",\n \"docDatas\": [{\n \"document\": {\n \"id\": \"c69d84b5-cc58-4117-86f3-2ce4fb124e7f\",\n \"meta\": {\n \"name\": \"Zone 2\"\n }\n },\n \"baseMeta\": {\n \"createdTime\": {\n \"seconds\": \"1747220128310\"\n },\n \"author\": \"60029267674\",\n \"collaborationId\": \"1248078836284880107\",\n \"current\": {\n \"version\": 0,\n \"time\": {\n \"seconds\": \"1747220128310\"\n },\n \"modifiedBy\": \"60029267674\"\n }\n }\n }]\n}}", "message": "Zone created successfully.", "request_uri": "/vani/api/v1/editions/60029715808/spaces/1303000000628003/zones", "status": "success" }

Code Examples

cURL Command line HTTP client
cURL
curl -X POST "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "create_zone": { "zone_name": "Zone 6" } }'

POST Duplicate

POST https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/duplicate
Required Scopes:
vani.spaces.create

Duplicate a specific Zone into an existing Space.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
zone_id string path Required The unique ID of the Zone to duplicate.
destination_type string body Based on Request The type of destination for the duplicate Zone. Allowed values: EXISTING_SPACE or NEW_SPACE.
destination_space_id string body Based on Request The ID of the destination Space where the Zone will be duplicated (required when destination_type is EXISTING_SPACE).
zone_name string body Based on Request The name for the duplicated Zone.
version_id string body Based on Request The ID of the version to duplicate.

Request Body

JSON
{ "duplicate_zone": { "destination_type": "SAME_SPACE" } }

Responses

200 SAME SPACE DUPLICATE - SUCCESS
404 SAME SPACE DUPLICATE - zone not found
401 SAME SPACE DUPLICATE - UNAUTHORIZED
200 DUPLICATE IN EXISTING SPACE - success
200 DUPLICATE IN EXISTING SPACE WITH NEW DOC NAME - success
200 DUPLICATE IN EXISTING SPACE WITH VERSION ID - success
404 DUPLICATE IN EXISTING SPACE - ZONE NOT FOUND
401 DUPLICATE IN EXISTING SPACE - UNAUTHORIZED
200 NEW SPACE - SUCCESS
200 NEW SPACE - SUCCESS WITH SPACE NAME
404 NEW SPACE - ZONE NOT FOUND
200 NEW SPACE - WITH VERSION ID
401 NEW SPACE - UNAUTHORIZED
SAME SPACE DUPLICATE - SUCCESS - Response
{ "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" }

Code Examples

cURL Command line HTTP client
cURL
curl -X POST "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/duplicate" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "duplicate_zone": { "destination_type": "SAME_SPACE" } }'

POST Move

POST https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/move
Required Scopes:
vani.spaces.create

Move a specific Zone from one Space to another.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
zone_id string path Required The unique ID of the Zone to move.
destination_type string body Based on Request The type of destination for the duplicate Zone. Allowed values: EXISTING_SPACE or NEW_SPACE.
move_zone string body Based on Request A JSON object that includes details to move the Zone. Allowed values: destination_type (EXISTING_SPACE or NEW_SPACE), space_name, team_id, destination_space_id.

Request Body

JSON
{ "move_zone":{ "destination_type":"NEW_SPACE", "team_id":{{team_id}}, "space_name":"testing move zone with params" } }

Responses

200 SUCCESS - NEWSPACE
404 ZONE NOT FOUND - NEWSPACE
401 UNAUTHORIZED - NEWSPACE
200 SUCCESS - EXISTING SPACE
404 ZONE NOT FOUND - EXISTING SPACE
404 SPACE NOT FOUND - EXISTING SPACE
401 UNAUTHORIZED - EXISTING SPACE
SUCCESS - NEWSPACE - Response
{ "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": "testing move zone with params", "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" }

Code Examples

cURL Command line HTTP client
cURL
curl -X POST "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/move" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "move_zone": { "destination_type": "NEW_SPACE", "team_id": "{{team_id}}", "space_name": "testing move zone" } }'

PUT Zone Restore

PUT https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/state
Required Scopes:
vani.spaces.update

Restore a specific Zone within a Space by updating its state.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
zone_id string path Required The unique ID of the Zone to restore.
zone_state string body Based on Request The value must be set to RESTORE to restore the Zone. Note: Only trashed Zones can be restored. Trying to restore any other type will result in an error.

Request Body

JSON
{ "zone_state": "RESTORE" }

Responses

200 success
400 already restored or deleted
401 unauthorized
success - Response
{ "data": { "current_user_id": "96384499", "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "space_state": "RESTORE", "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" }

Code Examples

cURL Command line HTTP client
cURL
curl -X PUT "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/state" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "zone_state": "RESTORE" }'

PUT Zone Trash

PUT https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/state
Required Scopes:
vani.spaces.update

Move a specific Zone to the "trash" state within a Space.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
zone_id string path Required The unique ID of the Zone to trash.
zone_state string body Based on Request The value must be set to , TRASH to consider the Zone as trashed. Note: Only active Zones can be trashed. Trying to trash any other type will result in an error.

Request Body

JSON
{ "zone_state": "TRASH" }

Responses

200 success
400 zone threshold violation
400 zone is already trashed or deleted
401 unauthorized
success - Response
{ "data": { "current_user_id": "96384499", "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "space_state": "TRASH", "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" }

Code Examples

cURL Command line HTTP client
cURL
curl -X PUT "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/state" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "zone_state": "TRASH" }'

PUT Zone Meta Update

PUT https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/meta
Required Scopes:
vani.spaces.update

Updates the metadata of a specific Zone.

Parameters

Name Type In Required Description
edition_id string path Required The unique ID of the edition.
space_id string path Required The unique ID of the Space.
zone_id string path Required The unique ID of the Zone to update.
zone_name string body Based on Request The name of the Zone.

Request Body

JSON
{ "zone_name": "test" }

Responses

200 success
409 same name
404 zone not found
401 unauthorized
success - Response
{ "data": { "current_user_id": "96384499", "zone_id": "598356E6-5F86-45FA-A7D5-ED8BB6D40DAE", "edition_id": "97375109", "space_id": "1505000000022005", "new_name": "test" }, "message": "Zone name updated successfully.", "request_uri": "/vani/api/v1/editions/97375109/spaces/1505000000022005/zones/598356E6-5F86-45FA-A7D5-ED8BB6D40DAE/meta", "status": "success" }

Code Examples

cURL Command line HTTP client
cURL
curl -X PUT "https://api.app.vanihq.com/vani/api/v1/editions/{edition_id}/spaces/{space_id}/zones/{zone_id}/meta" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "zone_name": "rename" }'