Update project
const url = 'https://api.deploybase.eu/api/v1/api/v1/projects/example';const options = { method: 'PATCH', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"analytics_enabled":true,"auto_deploy_enabled":true,"build_command":"example","default_branch":"example","forgejo_audience":"example","framework":"nextjs","git_auth_mode":"pat","git_provider":"github","git_repo_url":"example","git_token":"example","mr_previews_enabled":true,"name":"example","output_dir":"example","package_manager":"npm","platform_url_mode":"example","preview_branch_exclude":["example"],"preview_branch_include":["example"],"preview_branch_mode":"example","preview_slug":"example","primary_domain_id":"example","root_directory":"example","skip_git_validation":true,"subdomain":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.deploybase.eu/api/v1/api/v1/projects/example \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "analytics_enabled": true, "auto_deploy_enabled": true, "build_command": "example", "default_branch": "example", "forgejo_audience": "example", "framework": "nextjs", "git_auth_mode": "pat", "git_provider": "github", "git_repo_url": "example", "git_token": "example", "mr_previews_enabled": true, "name": "example", "output_dir": "example", "package_manager": "npm", "platform_url_mode": "example", "preview_branch_exclude": [ "example" ], "preview_branch_include": [ "example" ], "preview_branch_mode": "example", "preview_slug": "example", "primary_domain_id": "example", "root_directory": "example", "skip_git_validation": true, "subdomain": "example" }'Updates an existing project (partial update)
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Project ID (UUID)
Request Body
Section titled “ Request Body ”Project updates
object
AnalyticsEnabled switches site analytics (DEP-17). false stops collection and permanently deletes the project’s collected statistics, so switching off requires the admin role.
ForgejoAudience is the value Forgejo generates for an Authorized Integration. Not a secret, so it is accepted and returned in plain text.
GitAuthMode selects how deploybase authenticates to the git host (DEP-447): “pat” (default) uses a stored token; “forgejo_jwt” mints a short-lived JWT per operation and stores nothing. The latter needs Forgejo 16.0+ and an audience.
Whether merge/pull request events build previews. Independent of the branch policy.
PlatformURLMode decides what {subdomain}.sites.deploybase.eu does once a primary domain is set: “redirect” (default) 301s it to the primary, “serve” keeps it answering content. Requires the admin role.
Replaces the exclude list, evaluated before the include list. Send [] to clear it.
Replaces the include list. Send [] to clear it. Maximum 32 patterns.
Which webhook pushes auto-build a preview: “all”, “none” (only the default branch) or “custom”. Each policy field is independently optional; an omitted one keeps its stored value. The default branch always builds.
PreviewSlug renames the label preview hostnames are built from ({branch}-{preview_slug}.previews.deploybase.eu). Globally unique; check availability with GET /api/v1/projects/check-preview-slug first.
PrimaryDomainID makes one of this project’s verified domains canonical: every other hostname the project answers on then 301s to it. Send “” to clear it and go back to serving every hostname. Requires the admin role.
No oneof/uuid binding tag on purpose: a binding failure is a blanket 400 that
names no field, and this must answer 422 saying which value was wrong (DEP-287).
Responses
Section titled “ Responses ”OK
object
object
object
Site analytics (DEP-17). On by default; switching it off stops collection and deletes the project’s site_analytics_daily rows.
Auto-deploy (GitHub webhook) fields
AutoDeployPauseReason says why; the only value is AutoDeployPauseReasonRepeatedFailures.
AutoDeployPausedAt is when the breaker tripped. NULL means auto-deploy is not paused.
Auto-deploy circuit breaker (DEP-544). All five are SYSTEM state, written only by the dedicated repository methods (RecordBuildFailure, ResetBuildFailureStreak) and never by ProjectRepository.Update, which omits them: a settings save that read the row before the breaker tripped must not be able to write the pause back out.
They are deliberately separate from AutoDeployEnabled, the user’s own setting, which the platform never writes. See AutoDeployPaused in preview_branch_policy.go.
ConsecutiveBuildFailures counts user-caused failures sharing LastBuildFailureSignature.
Provenance (DEP-674, migration 000113): how the request that created this project was authenticated (proven: session or api_key) and which of our clients says it sent it (claimed, from X-Deploybase-Client). Written once by Create and omitted by ProjectRepository.Update. nil = unknown, including every project from before 000113.
object
ForgejoAudience is the aud value Forgejo generates for an Authorized Integration. Forgejo’s docs state it is not confidential, so unlike GitTokenEncrypted it is stored in plain text AND returned by the API – the user has to read it back to check it against their Forgejo settings.
GitAuthMode selects which credential ResolveProjectToken produces (DEP-447). “pat” is the historical behaviour; “forgejo_jwt” mints a short-lived JWT per call against ForgejoAudience and stores nothing. Empty is treated as “pat” so a row loaded before the migration, or a struct built in a test, still behaves.
Optional FK to team_git_connections; nil = manual PAT
LastBuildFailureMessage is the classified error line of the current streak, which the pause banner shows. Never raw build output.
MRPreviewsEnabled governs merge/pull-request previews on its own: the branch policy above never applies to an MR event.
PackageManager overrides the Node package manager used at build time. nil = auto-detect (lockfile / packageManager field); set = user override.
PlatformURLMode is read only when PrimaryDomainID is set. See PlatformURLMode.
Preview branch policy (DEP-287). Decides which webhook pushes auto-build a preview; see ShouldAutoBuildBranch in preview_branch_policy.go. Nothing here touches manual/API/MCP/ZIP deploys, and the default branch is never filtered.
PreviewSlug is the MUTABLE, globally unique label that preview hostnames are derived from: {branch}-{preview_slug}.previews.deploybase.eu (DEP-436). It drives hostnames and nothing else — never a storage path, never a manifest. Globally unique because the previews zone is shared by every team, so the hostname namespace is global.
PrimaryDomainID is the project’s canonical hostname, as a foreign key into
domains — deliberately not a copy of the hostname string (DEP-112). The route
reconciler recomputes every pointer from this FK on each sweep, so a wrong
redirect is drift it can see and repair; a denormalised host column would be read
back by that same reconciler and confirmed rather than fixed, and the 301 it
produces is cached at the edge for 30 days.
NULL means no canonical hostname: every hostname serves content directly, which is the behaviour every project had before DEP-112.
ProductionBranchDeletedAt is when a push deleted the production branch (EffectiveDefaultBranch). Cleared by the next push to that branch and by a change of DefaultBranch. nil = not known to be deleted.
ProvisionalUntil is set while a project created by a folder upload has not published yet (DEP-671, migration 000109). The project and its upload session are created together so the chosen address is held by the unique index from the start; past this time the upload sweeper deletes the project if it is still empty. NULL for every other project.
SYSTEM state, like the breaker columns below: written only by Create and the dedicated repository methods, and omitted by ProjectRepository.Update, so a stale struct saved by the publisher can never put a deadline back on an adopted project.
RepoDefaultBranch is the forge’s default branch as the last push reported it. nil when no push has reported one; Bitbucket Cloud push payloads never do.
ScreenshotDeploymentID is the live deployment’s id when a screenshot of it is stored (DEP-270), else absent. Fetch it from GET /projects/{id}/screenshot?d={this id}.
Slug is IMMUTABLE. It is the storage key — the middle segment of every deployed object’s path ({team_id}/{slug}/{deployment_id}/…) and the project_slug baked into each deployment’s write-once route manifest. Renaming it makes the router answer 500 slug_mismatch for every deployment already built. Use PreviewSlug to rename a hostname.
Production URL fields
Example
{ "data": { "created_client": "dashboard", "created_via": "session", "framework": "nextjs", "package_manager": "npm", "platform_url_mode": "redirect", "preview_branch_mode": "all", "status": "active" }}Bad Request
object
object
Example generated
{ "code": "example", "details": "example", "error": "example", "meta": { "request_id": "example", "timestamp": "example", "trace_id": "example" }}Unauthorized
object
object
Example generated
{ "code": "example", "details": "example", "error": "example", "meta": { "request_id": "example", "timestamp": "example", "trace_id": "example" }}Not Found
object
object
Example generated
{ "code": "example", "details": "example", "error": "example", "meta": { "request_id": "example", "timestamp": "example", "trace_id": "example" }}Invalid input. INVALID_BUILD_SETTINGS names the refused field in details.field; GIT_VALIDATION_FAILED carries details.git_error_code
object
object
Example generated
{ "code": "example", "details": "example", "error": "example", "meta": { "request_id": "example", "timestamp": "example", "trace_id": "example" }}Live 174db30c built