Introduction

Getting Started

RenderCache syncs simulation caches and textures between studio sites through regional cache nodes. You can drive transfers from the console, from the rcd CLI agent or through the REST API — for example from a Houdini post-render script or a render manager event.

1. 01

   Accept the workspace invitation

2. 02

   Install rcd on your nodes

3. 03

   Issue a service token

4. 04

   Call POST /api/v1/sync

Installing the agent

Install rcd on every machine that sends or receives caches: simulation workstations, file servers and render farm nodes. Supported: Linux x86_64 (glibc 2.28+) and Windows Server 2019+.

# Package from the RenderCache repository (RHEL / Rocky 8+)
sudo dnf install -y https://get.rendercache.ru/rcd/rcd-2.4.1.x86_64.rpm

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

# PowerShell as Administrator
msiexec /i https://get.rendercache.ru/rcd/rcd-2.4.1-x64.msi /qn

rcd login --workspace northlight
rcd agent register --name ws-fx-07 --role source --region msk
Start-Service rcd

Your first sync

A sync job describes what to send (a cache 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.rendercache.ru/api/v1/sync \
  -H "Authorization: Bearer $RC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-sh0420-v14" \
  -d '{
    "project": "NH_0420",
    "source": "/mnt/cache/fx/fluid_sim_v04/fluid_sim_v04.$F4.vdb",
    "frames": { "start": 1001, "end": 1240 },
    "targets": ["farm-spb-*", "farm-msk-01"],
    "priority": "high",
    "verify": "blake3",
    "notify": "https://pipeline.studio.com/hooks/rendercache"
  }'

import os, requests

resp = requests.post(
    "https://api.rendercache.ru/api/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['RC_TOKEN']}",
        "Idempotency-Key": "4f1c2a9e-sh0420-v14",
    },
    json={
        "project": "NH_0420",
        "source": "/mnt/cache/fx/fluid_sim_v04/fluid_sim_v04.$F4.vdb",
        "frames": {"start": 1001, "end": 1240},
        "targets": ["farm-spb-*", "farm-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.rendercache.ru
Authorization: Bearer rcs_9wQ…redacted
Content-Type: application/json
Idempotency-Key: 4f1c2a9e-sh0420-v14

{
  "project": "NH_0420",
  "source": "/mnt/cache/fx/fluid_sim_v04/fluid_sim_v04.$F4.vdb",
  "frames": { "start": 1001, "end": 1240 },
  "targets": ["farm-spb-*", "farm-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 rcd. 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 rcs_ and are shown once, at creation.

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

{
  "id": "tok_01JBX2K8ZV",
  "name": "houdini-post-render",
  "token": "rcs_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-RC-Timestamp — Unix time in seconds;
• X-RC-Signature — v1= followed by the hex digest;
• compare signatures in constant time (hmac.compare_digest).

Data transfer

Chunked Uploads

Large 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. rcd 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.rendercache.ru/api/v1/uploads \
  -H "Authorization: Bearer $RC_TOKEN" \
  -d '{
    "project": "NH_0420",
    "path": "fx/fluid_sim_v04/fluid_sim_v04.1042.vdb",
    "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.rendercache.ru/api/v1/uploads/us_8Hq2fK3x/chunks/1873 \
  -H "Authorization: Bearer $RC_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "X-RC-Chunk-Hash: blake3:5d2a…09fe" \
  --data-binary @chunk_1873.enc

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 a cache or 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": ["farm-spb-01", "farm-spb-02", "farm-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 'farm-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