Introduction

Getting Started

Mesh-Sync syncs 3D geometry — meshes, point clouds, octrees and LODs — between studio sites through regional edge nodes. You can drive transfers from the console, from the msync CLI agent or through the REST API — for example from a Houdini post-build script or an Unreal build event.

1. 01

   Accept the workspace invitation

2. 02

   Install msync on your nodes

3. 03

   Issue a service token

4. 04

   Call POST /api/v1/sync

Installing the agent

Install msync on every machine that sends or receives geometry: pipeline workstations, file servers and site nodes. Supported: Linux x86_64 (glibc 2.28+) and Windows Server 2019+.

# Package from the Mesh-Sync repository (RHEL / Rocky 8+)
sudo dnf install -y https://get.mesh-sync.ru/msync/msync-2.4.1.x86_64.rpm

# Bind the node to your workspace and assign a role
msync login --workspace northlight
msync agent register --name node-spb-02 --role site --region spb
sudo systemctl enable --now msync

# PowerShell as Administrator
msiexec /i https://get.mesh-sync.ru/msync/msync-2.4.1-x64.msi /qn

msync login --workspace northlight
msync agent register --name ws-geo-07 --role source --region msk
Start-Service msync

Your first sync

A sync job describes what to send (a geometry path or frame sequence), where (agents or agent groups) and how (priority, verification). The API accepts the job asynchronously and returns its ID right away; poll for progress or receive it via webhook.

curl -X POST https://api.mesh-sync.ru/api/v1/sync \
  -H "Authorization: Bearer $MS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-sh0420-v14" \
  -d '{
    "project": "NH_0420",
    "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
    "frames": { "start": 1001, "end": 1240 },
    "targets": ["node-spb-*", "node-msk-01"],
    "priority": "high",
    "verify": "blake3",
    "notify": "https://pipeline.studio.com/hooks/mesh-sync"
  }'

import os, requests

resp = requests.post(
    "https://api.mesh-sync.ru/api/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['MS_TOKEN']}",
        "Idempotency-Key": "4f1c2a9e-sh0420-v14",
    },
    json={
        "project": "NH_0420",
        "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
        "frames": {"start": 1001, "end": 1240},
        "targets": ["node-spb-*", "node-msk-01"],
        "priority": "high",
        "verify": "blake3",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["sync_id"])  # sync_01JBX7Q4M2

POST /api/v1/sync HTTP/1.1
Host: api.mesh-sync.ru
Authorization: Bearer mss_9wQ…redacted
Content-Type: application/json
Idempotency-Key: 4f1c2a9e-sh0420-v14

{
  "project": "NH_0420",
  "source": "/mnt/geo/scene/city_block_v04/city_block_v04.$F4.glb",
  "frames": { "start": 1001, "end": 1240 },
  "targets": ["node-spb-*", "node-msk-01"],
  "priority": "high",
  "verify": "blake3"
}

A 202 Accepted response means the job is queued. Full field and response details are in the reference.

Security

Authentication

The API accepts two kinds of credentials: service tokens for scripts and integrations, and agent certificates (mTLS) for msync. Console user passwords are never accepted by the API.

Service tokens

Workspace administrators issue tokens under Settings → Service tokens or via the API. Send the token as Authorization: Bearer <token>. Tokens start with mss_ and are shown once, at creation.

curl -X POST https://api.mesh-sync.ru/api/v1/auth/tokens \
  -H "Authorization: Bearer $MS_ADMIN_TOKEN" \
  -d '{ "name": "houdini-post-build", "scopes": ["sync:write"], "ttl_days": 90 }'

{
  "id": "tok_01JBX2K8ZV",
  "name": "houdini-post-build",
  "token": "mss_9wQ…shown-once",
  "scopes": ["sync:write"],
  "expires_at": "2027-01-21T10:42:07Z"
}

Request signing

Key operations and webhooks are signed with HMAC-SHA256 over the string timestamp + "." + body. Requests with a timestamp older than 300 seconds are rejected.

• X-MS-Timestamp — Unix time in seconds;
• X-MS-Signature — v1= followed by the hex digest;
• compare signatures in constant time (hmac.compare_digest).

Data transfer

Chunked Uploads

Large geometry files are uploaded in 8 MiB chunks (the last one may be smaller). Each chunk is encrypted with AES-256-GCM on the client and carries a BLAKE3 hash of the plaintext. msync does this for you; use the API only if you are writing your own uploader.

Upload session

1. POST/api/v1/uploads — open a session with file name, size and manifest hash. Returns upload_id and chunk_size.
2. PUT/api/v1/uploads/{upload_id}/chunks/{index} — send a chunk. Chunks may be sent in parallel and in any order.
3. POST/api/v1/uploads/{upload_id}/complete — close the session; the server checks the manifest and publishes the version.

curl -X POST https://api.mesh-sync.ru/api/v1/uploads \
  -H "Authorization: Bearer $MS_TOKEN" \
  -d '{
    "project": "NH_0420",
    "path": "scene/city_block_v04/city_block_v04.1042.glb",
    "size": 17083400192,
    "manifest_hash": "blake3:8e0f…c41a"
  }'

{
  "upload_id": "us_8Hq2fK3x",
  "chunk_size": 8388608,
  "chunks_total": 2037,
  "expires_at": "2026-10-30T10:42:07Z"
}

curl -X PUT https://api.mesh-sync.ru/api/v1/uploads/us_8Hq2fK3x/chunks/1873 \
  -H "Authorization: Bearer $MS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-MS-Chunk-Hash: blake3:5d2a…09fe" \
  --data-binary @chunk_1873.enc

Serving geometry from edge nodes

Published geometry is served by the nearest edge node over content-addressed paths. Mesh and sequence chunks are requested at /v2/geometry/<hash>/chunk.bin, while octree nodes and LOD bundles come from /bundles/octree/<node_id>/node.pak. Both paths return an ETag and Cache-Control: immutable and support Range for resuming.

curl -L -C - -o chunk_1873.bin \
  -H "Authorization: Bearer $MS_TOKEN" \
  "https://cdn.mesh-sync.ru/v2/geometry/5d2a09fe…c41a/chunk.bin"

# octree node (LOD bundle)
curl -L -o node.pak \
  -H "Authorization: Bearer $MS_TOKEN" \
  "https://cdn.mesh-sync.ru/bundles/octree/0a3f…17b/node.pak"

Resuming

A session lives for 7 days. After a failure, call GET /api/v1/uploads/{upload_id}: the received field is a Base64 bitmap of accepted chunks. Send only the missing ones — re-sending an accepted chunk with the same hash is safe and returns 200.

{
  "upload_id": "us_8Hq2fK3x",
  "state": "interrupted",
  "chunks_total": 2037,
  "chunks_received": 1873,
  "received": "//////////////////8AAA…",
  "resume_from": 1873
}

API Reference

POST/api/v1/sync

Creates a sync job for geometry or a sequence to one or more agents. Idempotent when the Idempotency-Key header is sent (keys are kept for 24 hours).

Body parameters

Responses

{
  "sync_id": "sync_01JBX7Q4M2",
  "status": "queued",
  "project": "NH_0420",
  "manifest": { "version": 14, "files": 240, "bytes": 17083400192, "chunks": 2048 },
  "delta": { "chunks_to_send": 164, "bytes_to_send": 1375731712 },
  "targets": ["node-spb-01", "node-spb-02", "node-msk-01"],
  "links": { "self": "/api/v1/sync/sync_01JBX7Q4M2" }
}

{
  "error": { "code": "token_invalid", "message": "Token is missing, expired or revoked." }
}

{
  "error": {
    "code": "sync_in_progress",
    "message": "An identical sync for these targets is already running.",
    "sync_id": "sync_01JBX6ZP0D"
  }
}

{
  "error": {
    "code": "validation_failed",
    "fields": { "targets": "No agent matches 'node-ams-*'." }
  }
}

Error codes

Errors are returned with an HTTP status and an error object carrying a machine-readable code.

Rate limits

Control endpoints are limited to 600 requests per minute per workspace; chunk uploads are limited only by your plan's bandwidth. Current limit state is returned in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Updated 20 October 2026 · API v1.4 · API status