DocumentationAPI Reference

REST API Reference

The V1 API powers the desktop app and supports custom integrations. Every endpoint includes curl, TypeScript, and JSON examples you can copy directly.

Authentication

All API requests require a project key sent via the Authorization header. Keys use the usc_ prefix and can be generated from the web dashboard under project settings.

Base URL

https://usourcecontrol.com

Auth header

Bearer usc_...

Content type

application/json

Examplebash

curl -X POST https://usourcecontrol.com/api/v1/auth/validate-key \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json"

Endpoints

POST/api/v1/auth/validate-key

Validate project key

Authenticate a project key and receive project metadata including project ID, name, organization, and storage configuration.

curlbash

curl -X POST https://usourcecontrol.com/api/v1/auth/validate-key \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json"

Request body

No body — key is sent via Authorization header.

Responsejson

{
  "project": {
    "id": "proj_abc123",
    "name": "MyGame",
    "orgId": "org_xyz789",
    "orgName": "My Studio"
  }
}

TypeScriptts

const res = await fetch("https://usourcecontrol.com/api/v1/auth/validate-key", {
  method: "POST",
  headers: {
    "Authorization": "Bearer usc_your_project_key",
    "Content-Type": "application/json",
  },
});
const { project } = await res.json();
console.log(project.name); // "MyGame"

POST/api/v1/projects/{id}/sync

Sync file status

Compare local file hashes against remote to determine which files need uploading or downloading. Send an array of local file paths and their SHA-256 hashes.

curlbash

curl -X POST https://usourcecontrol.com/api/v1/projects/proj_abc123/sync \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "path": "Content/Maps/MainLevel.umap", "hash": "a1b2c3..." },
      { "path": "Content/Characters/Hero.uasset", "hash": "d4e5f6..." }
    ]
  }'

Request bodyjson

{
  "files": [
    { "path": "Content/Maps/MainLevel.umap", "hash": "a1b2c3..." },
    { "path": "Content/Characters/Hero.uasset", "hash": "d4e5f6..." }
  ]
}

Responsejson

{
  "toUpload": ["Content/Maps/MainLevel.umap"],
  "toDownload": ["Content/Characters/Enemy.uasset"],
  "conflicts": [],
  "upToDate": ["Content/Characters/Hero.uasset"]
}

TypeScriptts

const res = await fetch(`https://usourcecontrol.com/api/v1/projects/${projectId}/sync`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    files: localFiles.map(f => ({ path: f.path, hash: f.sha256 })),
  }),
});
const { toUpload, toDownload, conflicts } = await res.json();

POST/api/v1/projects/{id}/files/upload

Initiate file upload

Request a presigned upload URL for a file. Upload the file directly to storage using the returned URL, then call the confirm endpoint. Max file size: 10 GB.

curlbash

curl -X POST https://usourcecontrol.com/api/v1/projects/proj_abc123/files/upload \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "Content/Maps/MainLevel.umap",
    "hash": "a1b2c3...",
    "size": 524288000
  }'

Request bodyjson

{
  "path": "Content/Maps/MainLevel.umap",
  "hash": "a1b2c3...",
  "size": 524288000
}

Responsejson

{
  "uploadUrl": "https://storage.bunnycdn.com/...",
  "fileId": "file_abc123",
  "confirmUrl": "/api/v1/projects/{id}/files/upload/confirm"
}

TypeScriptts

// Step 1: Get presigned URL
const initRes = await fetch(`https://usourcecontrol.com/api/v1/projects/${projectId}/files/upload`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ path: "Content/Maps/MainLevel.umap", hash, size }),
});
const { uploadUrl, fileId, confirmUrl } = await initRes.json();

// Step 2: Upload file to storage
await fetch(uploadUrl, { method: "PUT", body: fileBuffer });

// Step 3: Confirm upload
await fetch(`https://usourcecontrol.com${confirmUrl}`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({ fileId }),
});

POST/api/v1/projects/{id}/commits

Create commit

Batch-commit uploaded files with a message. All files must be confirmed before committing. Commits are sequentially numbered per project. Max 10,000 files per commit.

curlbash

curl -X POST https://usourcecontrol.com/api/v1/projects/proj_abc123/commits \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Updated hero animations",
    "files": [
      { "fileId": "file_abc123", "action": "modified" },
      { "fileId": "file_def456", "action": "added" }
    ]
  }'

Request bodyjson

{
  "message": "Updated hero animations",
  "files": [
    { "fileId": "file_abc123", "action": "modified" },
    { "fileId": "file_def456", "action": "added" }
  ]
}

Responsejson

{
  "commit": {
    "id": "commit_abc123",
    "number": 25,
    "message": "Updated hero animations",
    "fileCount": 2,
    "createdAt": "2026-04-16T14:30:00Z"
  }
}

TypeScriptts

const res = await fetch(`https://usourcecontrol.com/api/v1/projects/${projectId}/commits`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    message: "Updated hero animations",
    files: uploadedFiles.map(f => ({ fileId: f.id, action: f.action })),
  }),
});
const { commit } = await res.json();
console.log(`Commit #${commit.number} created`);

GET/api/v1/projects/{id}/files/{fileId}/versions

List file versions

Retrieve every version of a file with download URLs and metadata. Versions are ordered from newest to oldest.

curlbash

curl -X GET https://usourcecontrol.com/api/v1/projects/proj_abc123/files/file_abc123/versions \
  -H "Authorization: Bearer usc_your_project_key"

Request body

No body — key is sent via Authorization header.

Responsejson

{
  "versions": [
    {
      "version": 12,
      "hash": "a1b2c3...",
      "size": 524288000,
      "downloadUrl": "https://cdn.usourcecontrol.com/...",
      "uploadedBy": "Sarah Chen",
      "createdAt": "2026-04-16T14:30:00Z"
    }
  ]
}

TypeScriptts

const res = await fetch(
  `https://usourcecontrol.com/api/v1/projects/${projectId}/files/${fileId}/versions`,
  { headers: { "Authorization": `Bearer ${apiKey}` } },
);
const { versions } = await res.json();
const latest = versions[0];
console.log(`v${latest.version} — ${latest.uploadedBy}`);

POST/api/v1/projects/{id}/restore

Restore file version

Restore one or more files to a previous version. This creates new versions with the restored content, preserving history.

curlbash

curl -X POST https://usourcecontrol.com/api/v1/projects/proj_abc123/restore \
  -H "Authorization: Bearer usc_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "fileId": "file_abc123", "version": 8 }
    ]
  }'

Request bodyjson

{
  "files": [
    { "fileId": "file_abc123", "version": 8 }
  ]
}

Responsejson

{
  "restored": [
    {
      "fileId": "file_abc123",
      "previousVersion": 12,
      "restoredVersion": 8,
      "newVersion": 13
    }
  ]
}

TypeScriptts

const res = await fetch(`https://usourcecontrol.com/api/v1/projects/${projectId}/restore`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    files: [{ fileId: "file_abc123", version: 8 }],
  }),
});
const { restored } = await res.json();
console.log(`Restored to v${restored[0].restoredVersion}, new version: v${restored[0].newVersion}`);