Skip to content
deploybase

Create project

POST
/api/v1/projects
 
curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/projects \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "auto_deploy_enabled": true, "branch": "example", "build_command": "example", "default_branch": "example", "deploy": true, "forgejo_audience": "example", "framework": "nextjs", "git_auth_mode": "pat", "git_provider": "github", "git_repo_url": "example", "git_token": "example", "git_username": "gitlab+deploy-token-123", "mr_previews_enabled": true, "name": "example", "output_dir": "example", "package_manager": "npm", "preview_branch_exclude": [ "example" ], "preview_branch_include": [ "example" ], "preview_branch_mode": "example", "root_directory": "example", "skip_git_validation": true, "slug": "example", "subdomain": "example" }'

Creates a new static site project for the authenticated team. With subdomain, that exact production address is reserved or the request is refused with alternatives. With deploy: true (and a git repository and branch) the first build starts in the same call, and data becomes {project, deployment_id} when it started or {project, deploy_error: {status, code, message}} when the project was created but the build could not start (still a 201; the code is what POST /deployments would answer). With auto_deploy_enabled and a token that can read the repository but may not add the push webhook (the host answered 401, 403 or 404), the project is still created, with auto_deploy_enabled false and data.warnings [{code: webhook_not_added, message}].

Authorizations

Section titled “ Authorizations ”

Request Body

Section titled “ Request Body ”

Project details

Media type application/json
object
auto_deploy_enabled

AutoDeployEnabled, when true, registers a webhook at create time so the flow stays a single atomic call (no post-create PATCH). Requires a git source whose provider supports auto-deploy and a resolvable token; otherwise creation is rejected.

boolean
branch

Branch is the branch the first build deploys, typically detection’s default branch. Only read with deploy: true. When default_branch is not sent, it becomes the project’s default branch too, so the first build goes to production.

string
<= 255 characters
build_command
string
<= 1024 characters
default_branch
string
<= 255 characters
deploy

Deploy starts the first build in the same call (DEP-671). It needs git_repo_url and a branch (branch, else default_branch). The response is then {project, deployment_id} or, when the project was created but the build could not start, {project, deploy_error}; either way a 201, because the project exists.

boolean
forgejo_audience

ForgejoAudience is the value Forgejo generates for an Authorized Integration. Not a secret, so it is accepted and returned in plain text.

string
<= 255 characters
framework
string
Allowed values: nextjs sveltekit astro hugo vite gatsby jekyll static-html other
git_auth_mode

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.

string
Allowed values: pat forgejo_jwt
git_provider

GitProvider names the git host. Omitted with a GitLab token (glpat-, gldt-), it is stored as gitlab, which also covers self-hosted GitLab.

string
Allowed values: github gitlab bitbucket codeberg
git_repo_url
string
git_token
string
<= 500 characters
git_username

GitUsername is sent with git_token instead of the provider default. Only needed for a GitLab deploy token (gldt-), which works only with its own username, e.g. gitlab+deploy-token-123. Letters, digits and . + _ - only; requires git_token.

string
<= 255 characters

Example 

gitlab+deploy-token-123
mr_previews_enabled

Whether merge/pull request events build previews (default true). Independent of the branch policy, which never applies to MR events.

boolean
name
required
string
>= 1 characters <= 255 characters
output_dir
string
<= 255 characters
package_manager
string
Allowed values: npm pnpm yarn bun
preview_branch_exclude

Branch patterns evaluated before the include list under mode “custom”; a match blocks the build. “Everything except bots” is include [“”], exclude [“renovate/”].

Array<string>
preview_branch_include

Branch patterns that opt a branch in under mode “custom”. Exact name, or one “” alone or at either end (e.g. “release/”, “*-beta”). Maximum 32.

Array<string>
preview_branch_mode

Which webhook pushes auto-build a preview: “all” (default), “none” (only the default branch) or “custom”. The default branch always builds, under every mode.

string
root_directory
string
<= 255 characters
skip_git_validation
boolean
slug
string
>= 1 characters <= 255 characters
subdomain

Subdomain is the production address to reserve, {subdomain}.sites.deploybase.eu (DEP-671). Reserved exactly or refused: 422 SUBDOMAIN_INVALID / SUBDOMAIN_RESERVED or 409 SUBDOMAIN_TAKEN, each with details.suggestions. Omit it to have one derived from the name (with a random suffix if that is taken). GET /projects/suggest-subdomain returns the one a create would derive, so a page can show it first.

No binding tag on purpose: a binding failure is a blanket 400 naming no field, and this must answer 422 with suggestions.

string

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Without deploy; with deploy: true, data is a CreateProjectResponse

Media type application/json
object
data
meta
object
request_id
string
timestamp
string
trace_id
string
data
object
analytics_enabled

Site analytics (DEP-17). On by default; switching it off stops collection and deletes the project’s site_analytics_daily rows.

boolean
auto_deploy_enabled

Auto-deploy (GitHub webhook) fields

boolean
auto_deploy_pause_reason

AutoDeployPauseReason says why; the only value is AutoDeployPauseReasonRepeatedFailures.

string
auto_deploy_paused_at

AutoDeployPausedAt is when the breaker tripped. NULL means auto-deploy is not paused.

string
build_command
string
bunny_edge_rule_guid
string
bunny_not_found_edge_rule_guid
string
bunny_pull_zone_id
integer
consecutive_build_failures

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.

integer
created_at
string
created_client
string
Allowed values: dashboard cli mcp migrate
created_via

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.

string
Allowed values: session push api_key agent_token
default_branch
string
features
object
http_functions
boolean
forgejo_audience

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.

string
framework
string
Allowed values: nextjs sveltekit astro hugo vite gatsby jekyll static-html other
git_auth_mode

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.

string
git_connection_id

Optional FK to team_git_connections; nil = manual PAT

string
git_provider
string
git_repo_url
string
git_username

GitUsername is the HTTP Basic username sent with the stored PAT instead of the provider default (DEP-810). A GitLab deploy token is only accepted with its own username, e.g. gitlab+deploy-token-123. Not a secret, so it is returned by the API. Set only alongside a stored PAT; cleared with it and by the keyless Forgejo mode.

string
has_git_token
boolean
has_webhook_secret
boolean
id
string
last_build_failure_message

LastBuildFailureMessage is the classified error line of the current streak, which the pause banner shows. Never raw build output.

string
live_deployment_id
string
mr_previews_enabled

MRPreviewsEnabled governs merge/pull-request previews on its own: the branch policy above never applies to an MR event.

boolean
name
string
output_dir
string
package_manager

PackageManager overrides the Node package manager used at build time. nil = auto-detect (lockfile / packageManager field); set = user override.

string
Allowed values: npm pnpm yarn bun
platform_url_mode

PlatformURLMode is read only when PrimaryDomainID is set. See PlatformURLMode.

string
Allowed values: redirect serve
preview_branch_exclude
Array<string>
preview_branch_include
Array<string>
preview_branch_mode

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.

string
Allowed values: all none custom
preview_slug

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.

string
primary_domain_id

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.

string
production_branch_deleted_at

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.

string
production_url
string
provisional_until

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.

string
repo_default_branch

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.

string
root_directory
string
screenshot_deployment_id

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}.

string
slug

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.

string
status
string
Allowed values: active deleting
subdomain

Production URL fields

string
team_id
string
updated_at
string
warnings

Warnings is set only by POST /projects without deploy: what the create did not do although the project exists (webhook_not_added, DEP-810). Absent otherwise.

Array<object>
object
code

Code is stable for clients to switch on, e.g. webhook_not_added.

string
message

Message says it in words, for the page.

string

Example 

{
  "data": {
    "created_client": "dashboard",
    "created_via": "session",
    "framework": "nextjs",
    "package_manager": "npm",
    "platform_url_mode": "redirect",
    "preview_branch_mode": "all",
    "status": "active",
    "warnings": [
      {
        "code": "webhook_not_added"
      }
    ]
  }
}

400

Section titled “ 400 ”

Bad Request

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

401

Section titled “ 401 ”

Unauthorized

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

402

Section titled “ 402 ”

PLAN_LIMIT_EXCEEDED: site limit reached

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

409

Section titled “ 409 ”

SUBDOMAIN_TAKEN with details.suggestions, or PROJECT_NAME_TAKEN with details.field name

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

422

Section titled “ 422 ”

SUBDOMAIN_INVALID or SUBDOMAIN_RESERVED with details.suggestions; INVALID_BUILD_SETTINGS names the refused field in details.field; GIT_VALIDATION_FAILED carries details.git_error_code, and with auth_failed details.git_error_reason (token_not_accepted: the host answered 401; token_cannot_read: 403, the token may not read code; token_needs_fine_grained: 403, the GitLab group accepts only fine-grained tokens); INVALID_INPUT with details.field deploy or branch

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

Live a8b7eb1d built