API Reference

The Diversion REST API allows automation tools and CI/CD pipelines to interact with workspaces, locks, branches, and sync operations. All endpoints are authenticated with API tokens.

Authentication

Authorization: Bearer <YOUR_API_TOKEN>

Generate tokens in the Diversion dashboard or via CLI: diversion token create ci-bot --scope sync,locks:read

Base URL

https://api.diversionhq.org/v1

Endpoints

Method	Path	Description
GET	/workspaces	List all workspaces
GET	/workspaces/:id/branches	List branches
POST	/workspaces/:id/sync	Trigger a sync
GET	/workspaces/:id/locks	List active locks
POST	/workspaces/:id/locks	Acquire a lock
DELETE	/workspaces/:id/locks/:path	Release a lock
POST	/workspaces/:id/hooks	Register a build webhook

Example: Trigger Sync

curl -X POST https://api.diversionhq.org/v1/workspaces/ws_abc123/sync \
  -H "Authorization: Bearer dvn_tok_..." \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

{
  "sync_id": "sync_7f2c9a",
  "status": "queued",
  "branch": "main",
  "estimated_objects": 12847
}

Example: Acquire Lock

curl -X POST https://api.diversionhq.org/v1/workspaces/ws_abc123/locks \
  -H "Authorization: Bearer dvn_tok_..." \
  -H "Content-Type: application/json" \
  -d '{"path": "Content/Maps/City_Hub.umap", "type": "exclusive", "ttl": "4h"}'