Projects

A project combines source code, build configuration, environment variables, domains, and deployment history. Create a project record first, then submit a deployment.

Local filesystem and edge administration operations require self-hosted capabilities, which every Synq install has. (Hosted-cloud scopes are switched off in Synq; see Cloud compatibility.)

Create a project

Create a project from a git repo or a local path, baking the build config into the project row. For an uploaded folder, use the source upload flow instead. Only name is required — everything else is auto-detected or defaulted.

const result = await ship.projects.create({
  name: "marketing-site",
  gitOwner: "acme",
  gitRepo: "site",
  gitBranch: "main",
  framework: "nextjs",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/projects" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"marketing-site","gitOwner":"acme","gitRepo":"site","gitBranch":"main","framework":"nextjs"}'

Scale a stateless application on a cluster

Self-hosted projects can target a ready K3s server cluster. Saving the target requires fleet administration. Choose a registry repository for source builds; cluster nodes pull immutable release images using the saved registry credentials. This currently supports a single stateless application or worker, without persistent mounts or a Compose stack. Database replication requires storage and an engine operator.

const current = await ship.projects.getClusterWorkload("proj_123");
await ship.projects.setClusterTarget("proj_123", {
  clusterId: "cluster_123",
  config: { replicas: 3, imageRepository: "ghcr.io/acme/api" },
  expectedUpdatedAt: current.updatedAt,
  stateless: true,
});
// Deploy the project through the existing Deployments API.
// After that release is active, change its replicas without rebuilding:
const live = await ship.projects.getClusterWorkload("proj_123");
if (live.activeDeploymentId && live.activeClusterId === live.clusterId) {
  const scale = await ship.projects.scaleClusterWorkload("proj_123", {
    replicas: 4,
    expectedDeploymentId: live.activeDeploymentId,
    expectedUpdatedAt: live.updatedAt,
  });
  console.log(scale.deploymentId); // Follow the normal deployment progress stream.
}

Replica changes are configuration releases. They reuse the active image, wait for ready pods and use the existing update/rollback history. Allow capacity for the old and new releases together. status and observedAt describe the last observation; saved config describes future intent. Synq Edge currently enters through the first cluster control server. Automatic gateway failover, database operators and policy-driven autoscaling are separate delivery stages.

Update a project

The update body is a partial of the create body — send only the fields you want to change. Every field above is accepted and optional here, plus these update-only fields:

const result = await ship.projects.update("proj_123", {
  buildCommand: "pnpm build",
  gitBranch: "release",
});
console.log(result);

curl -X PATCH "$SYNQ_URL/api/projects/proj_123" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildCommand":"pnpm build","gitBranch":"release"}'

Link a git repo

Attach (or re-point) a GitHub repository to an existing project. When branch is omitted, the repo's default branch is used.

const result = await ship.projects.linkRepo("proj_123", {
  owner: "acme",
  repo: "site",
  branch: "main",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/projects/proj_123/git/link" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"acme","repo":"site","branch":"main"}'

Related git routes: POST /api/projects/:id/branch (change the deploy branch), POST /api/projects/:id/auto-deploy (toggle deploy-on-push), GET /api/projects/:id/branches, and GET /api/projects/:id/commit-status (is the deployed commit behind remote HEAD?). See the GitHub API for connecting the GitHub App itself.

Connect a custom domain

A shortcut that adds a domain to the project and marks it primary in one call. For the full domain lifecycle (DNS preview, verification, SSL), use the Domains API.

const result = await ship.projects.connectDomain("proj_123", {
  domain: "app.example.com",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/projects/proj_123/connect" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.example.com"}'

Environment variables

GET   /api/projects/:id/env
PATCH /api/projects/:id/env

GET lists variables for the project with secret values masked. Writes go through a merge: only the keys you name are touched — upserts are inserted/updated, deletes are removed, and every other variable (including untouched masked secrets) is left intact.

const result = await ship.projects.mergeEnvVars("proj_123", {
  environment: "production",
  upserts: [
    {
      key: "DATABASE_URL",
      value: "postgres://…",
      isSecret: true,
    },
  ],
  deletes: ["OLD_FLAG"],
});
console.log(result);

curl -X PATCH "$SYNQ_URL/api/projects/proj_123/env" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "upserts": [{"key":"DATABASE_URL","value":"postgres://…","isSecret":true}],
    "deletes": ["OLD_FLAG"]
  }'

Resources

GET   /api/projects/:id/resources
PATCH /api/projects/:id/resources
POST  /api/projects/:id/resources

Read or update the CPU/RAM/disk allotment (separately for production and build), sleep behavior, and listen port. POST is an alias of PATCH. All fields are optional; send only what you want to change.

const result = await ship.projects.updateResources("proj_123", {
  production: {
    cpuCores: 1,
    memoryMb: 1024,
  },
  sleepMode: "always_on",
});
console.log(result);

curl -X PATCH "$SYNQ_URL/api/projects/proj_123/resources" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"production":{"cpuCores":1,"memoryMb":1024},"sleepMode":"always_on"}'

Sleep mode also has its own shortcut route: POST /api/projects/:id/sleep-mode.

Create an environment

POST /api/projects/:id/environments

Folder uploads

See Source files to upload a folder or deploy generated code.

Transfer to / from cloud

POST /api/projects/:id/transfer/to-cloud         † self-hosted only
POST /api/projects/:id/transfer/to-self-hosted   † self-hosted only

Hosted-cloud only, switched off in Synq. These promote a local project to a hosted cloud, or pull a cloud project back to this instance; a Synq install has no cloud to transfer to. They return 404 on the hosted cloud itself. Both require project:admin.

const result = await ship.projects.transferToCloud("proj_123");
console.log(result);

curl -X POST "$SYNQ_URL/api/projects/proj_123/transfer/to-cloud" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

Retry routing with logs

Routing repair can include SSH and certificate issuance. Use the streaming operation to follow its progress without the ordinary request timeout:

for await (const event of ship.projects.retryRoutingStream("proj_123")) {
  console.log(event.event, event.data);
}

The HTTP equivalent is POST /api/projects/:id/routing/retry/stream with an SSE response. Log events contain the server's messages. A terminal complete event carries status: "completed" or status: "failed"; a disconnected stream alone does not establish success. Cancelling the stream stops log delivery while an accepted repair continues under the project's runtime lock.

Errors

Operations

Lifecycle

Source and deployment

Cluster scaling

Cluster databases

Environments and settings

Volumes

Routing and monitoring

Connections, storage, and apps

Cloud transfer

HTTP endpoints