Integrations overview

Every integration speaks the same /api/v1 contract and uses the same credentials. They differ only in what sits between your bytes and the object store.

The matrix

Integration	Transport	Credential	Chunk dedup	Status
cav CLI	HTTPS + Git	cavs_pat_	via the agent	stable
Standard Git LFS	Git LFS basic + presigned URLs	any CAVS token	whole-object only	stable
CAVS LFS agent	custom transfer + …/lfs/*	cavs_pat_ / cavs_ci_	yes	stable
Python SDK	HTTPS + presigned URLs	cavs_pat_ / cavs_ci_	no (whole objects)	stable, v0.1.x
TypeScript SDK	HTTPS + presigned URLs	cavs_pat_ / cavs_ci_	no (whole objects)	stable, v0.1.x
GitHub Action	wraps the TS SDK	cavs_ci_	no	stable, v0.1.x
Webhooks	inbound HTTP to you	HMAC-SHA256 signature	—	stable
Plain HTTP	HTTPS + presigned URLs	any CAVS token	no	stable
Engine SDKs (Go, Node, Kotlin)	FFI over the Rust engine	n/a (content delivery)	yes	stable, versioned with the engine
Godot plugin	engine integration	n/a	yes	released

Tip

Chunk-level dedup only exists where the CAVS engine is in the path — the transfer agent or an engine SDK. The platform SDKs and the direct HTTP API move whole objects, which still dedups identical content but not similar content. Pick based on whether your files change or merely accumulate.

Packages

	Install	Registry
CLI	curl -fsSL https://raw.githubusercontent.com/orelvis15/cavs-hub-cli/main/install.sh | sh	GitHub Releases
Python SDK	pip install cavs	PyPI — cavs
TypeScript SDK	npm i @cavsnode/cavs-sdk	npm — @cavsnode/cavs-sdk
GitHub Action	uses: orelvis15/cavs-sdks/integrations/[email protected]	GitHub
Engine core + CLI	cargo install cavs-cli	crates.io
Engine SDK (Node)	npm i @orelvis15/cavs-sdk	npm
Engine SDK (Kotlin/JVM)	io.github.orelvis15:cavs-sdk	Maven Central
Engine SDK (Go)	go get github.com/orelvis15/cavs-oss/sdks/go	pkg.go.dev

Caution

Two different npm packages, easily confused. @cavsnode/cavs-sdk is the platform client — talks HTTP to CAVS Node. @orelvis15/cavs-sdk is the engine binding — chunking and fetching, no platform involved. Most people want the first.

Shared conventions

Everything below applies to every integration.

Base URL and auth

export CAVS_API=https://cavsnode.com     # SDKs and CLI
export CAVS_TOKEN=cavs_pat_...

Authorization: Bearer <token>

Telemetry headers

Clients identify themselves so the platform can attribute usage and warn about deprecations:

User-Agent: cavs-<lang>/<version>
X-CAVS-Client: python-sdk | javascript-sdk | cli
X-CAVS-Integration: cli | python-sdk | javascript-sdk | github-actions | gitlab-ci | generic-http | …
X-CAVS-Integration-Version: <version>
X-CAVS-Run-ID: <optional correlation id>

An SDK defaults X-CAVS-Integration to its own client id; integrations built on top override it — the GitHub Action sends github-actions, for example. If you’re writing your own client, set them: it’s how you’ll be identifiable when something goes wrong.

Idempotency

Idempotency-Key: <stable string>

Send it on creating an upload session, finalizing, and creating a snapshot. Resending the same key returns the same resource.

Errors

{ "error": { "code": "quota_exceeded", "message": "…", "request_id": "8c1f…" } }

Every client maps status codes to typed errors and retries 429 and 5xx up to four times with exponential backoff and jitter. See Errors.

Correlation

Responses carry X-Correlation-Id / X-Request-Id; error bodies embed request_id. Send your own X-Correlation-Id to thread a trace through.

Choosing

Files live in GitCLI + transfer agent. git push keeps working, with chunk-level dedup.

Files come out of a pipelinePython SDK. Verified uploads and downloads from training and ETL jobs.

Files come out of a buildGitHub Action, or the TypeScript SDK for anything more custom.

No SDK for your languageFour HTTP calls to upload, one to download.

You ship files to end usersEmbed chunk-level delivery in your app or game client.

You need to react to eventsSigned callbacks on push, release, quota and GC.

Roadmap

Documented in the SDK contract but not available today — calling them returns 404:

	Status
Service accounts, cavs_sk_ keys	not deployed; use cavs_ci_ tokens
Runs API and run→artifact lineage	not deployed; use /graph/edges
GET /resolve?uri=cavs://…	not deployed; resolve via repository + oid
MLflow (mlflow-cavs)	roadmap
Kubeflow (cavs-kfp)	roadmap
Airflow provider	roadmap
Go platform SDK (cavs-go)	roadmap
.NET SDK (CAVS.SDK)	roadmap
Unity / Unreal plugins	roadmap
Azure Blob / native GCS for BYOS	roadmap

Tracked in the SDK roadmap.