← Back to Documentation

API Reference

The TensorSync API is organized around REST principles. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.tensorsync.xyz/v2

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer tsk_your_api_key_here
⚠️ Security: Never expose your API key in client-side code or public repositories. Use environment variables or secret management tools.

Rate Limiting

API requests are rate-limited based on your plan:

Plan Requests/minute Requests/day
Researcher (Free) 60 10,000
Lab 300 100,000
Enterprise Custom Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300 X-RateLimit-Remaining: 299 X-RateLimit-Reset: 1625097600

Endpoints

Sync Operations

POST /sync/init

Initialize a new synchronization session for a repository.

Request Body

Parameter Type Required Description
repository string Required Repository name (e.g., "research/imagenet-2024")
compress boolean Optional Enable delta compression (default: true)
parallel_streams integer Optional Number of parallel sync streams (default: 4, max: 16)
region string Optional Target region (e.g., "eu-central", "us-west")

Example Request

curl -X POST https://api.tensorsync.xyz/v2/sync/init \ -H "Authorization: Bearer tsk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "repository": "research/imagenet-2024", "compress": true, "parallel_streams": 8, "region": "eu-central" }'

Response

200 OK
{ "session_id": "sync_abc123def456", "repository": "research/imagenet-2024", "status": "initialized", "created_at": "2026-06-16T12:00:00Z", "estimated_duration_seconds": 300, "websocket_url": "wss://edge.tensorsync.xyz/ws/sync_abc123def456" }
GET /sync/{session_id}/status

Get the current status of a synchronization session.

Path Parameters

Parameter Type Description
session_id string The synchronization session ID

Example Request

curl https://api.tensorsync.xyz/v2/sync/sync_abc123def456/status \ -H "Authorization: Bearer tsk_your_api_key"

Response

200 OK
{ "session_id": "sync_abc123def456", "status": "in_progress", "progress": { "percent": 67.5, "bytes_transferred": 675000000, "total_bytes": 1000000000, "files_synced": 150, "total_files": 222 }, "speed_mbps": 45.2, "eta_seconds": 98, "started_at": "2026-06-16T12:00:00Z", "updated_at": "2026-06-16T12:03:22Z" }

Models

GET /models

List all available models in your account.

Query Parameters

Parameter Type Required Description
limit integer Optional Maximum number of models to return (default: 20, max: 100)
offset integer Optional Number of models to skip (for pagination)
format string Optional Filter by format: safetensors, pytorch, tensorflow

Example Request

curl https://api.tensorsync.xyz/v2/models?limit=10&format=safetensors \ -H "Authorization: Bearer tsk_your_api_key"

Response

200 OK
{ "models": [ { "id": "model_llama3_70b", "name": "llama-3-70b", "format": "safetensors", "size_bytes": 140000000000, "versions": ["v1.0", "v2.0", "v2.1"], "latest_version": "v2.1", "created_at": "2026-05-15T10:30:00Z", "updated_at": "2026-06-10T14:22:00Z" }, { "id": "model_vit_base", "name": "vision-transformer-base", "format": "safetensors", "size_bytes": 346000000, "versions": ["v3.0", "v3.1", "v3.2.1"], "latest_version": "v3.2.1", "created_at": "2026-04-20T09:15:00Z", "updated_at": "2026-06-05T11:45:00Z" } ], "total": 2, "limit": 10, "offset": 0 }
GET /models/{model_id}/download

Get a presigned download URL for a specific model version.

Path Parameters

Parameter Type Description
model_id string The model ID

Query Parameters

Parameter Type Required Description
version string Optional Specific version (default: latest)
expires_in integer Optional URL expiration time in seconds (default: 3600, max: 86400)

Example Request

curl https://api.tensorsync.xyz/v2/models/model_llama3_70b/download?version=v2.1 \ -H "Authorization: Bearer tsk_your_api_key"

Response

200 OK
{ "download_url": "https://cdn.tensorsync.xyz/models/llama-3-70b/v2.1/model.safetensors?signature=abc123...", "expires_at": "2026-06-16T13:00:00Z", "size_bytes": 140000000000, "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb924..." }

Telemetry

POST /telemetry/stream

Start streaming real-time metrics from a training job via WebSocket.

💡 WebSocket Endpoint: After calling this endpoint, connect to the returned WebSocket URL to receive real-time metrics.

Request Body

Parameter Type Required Description
job_id string Required Training job ID
metrics array Optional List of metrics to stream (default: all)
interval integer Optional Update interval in seconds (default: 5)

Example Request

curl -X POST https://api.tensorsync.xyz/v2/telemetry/stream \ -H "Authorization: Bearer tsk_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "job_id": "training-job-42", "metrics": ["loss", "grad_norm", "gpu_util"], "interval": 5 }'

Response

200 OK
{ "websocket_url": "wss://edge.tensorsync.xyz/ws/telemetry_training-job-42", "expires_at": "2026-06-16T13:00:00Z", "metrics": ["loss", "grad_norm", "gpu_util"] }

WebSocket Message Format

{ "timestamp": "2026-06-16T12:05:30Z", "job_id": "training-job-42", "metrics": { "loss": 0.234, "grad_norm": 1.45, "gpu_util": 98.5 } }

Error Codes

The TensorSync API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Meaning Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error (contact support)

Error Response Format

{ "error": { "code": "invalid_parameter", "message": "The 'repository' parameter is required", "param": "repository", "doc_url": "https://tensorsync.xyz/docs/errors#invalid_parameter" } }

SDKs & Libraries

Official SDKs are available for popular languages:

Getting Help