Begin a direct upload for a new project

POST

/api/v1/uploads

curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/uploads \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "files": [ { "hash": "example", "path": "example", "size": 1 } ], "label": "example", "project": { "name": "example", "subdomain": "example" } }'

Creates the project and opens its upload session in one call, so a folder is never asked for after the project exists and the address shown is the one reserved (DEP-671). The files are checked (manifest, and whether it is a publishable site) before the project is created. The response carries the new project; PUT the files and finalize as with POST /projects/{id}/uploads. The project stays provisional until an upload to it publishes: if none does, it is deleted about 2 hours 15 minutes after the last begin, so an abandoned upload leaves no empty project. A retry after a failed PUT or finalize goes to POST /projects/{id}/uploads with the returned project id. Git can be connected to the project later.

Authorizations

• BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

Replaying this key returns the original session and project and creates nothing

Request Body

Project and upload manifest

Media type application/json

object

files

required

Array<object>

object

hash

string

path

string

size

integer

label

string

project

required

object

name

required

string

>= 1 characters <= 255 characters

subdomain

string

Example ^generated

{
  "files": [
    {
      "hash": "example",
      "path": "example",
      "size": 1
    }
  ],
  "label": "example",
  "project": {
    "name": "example",
    "subdomain": "example"
  }
}

Responses

201

Created

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

deployment_id

string

expires_at

string

known_count

integer

missing

Missing lists every unique manifest hash the client must PUT. In this phase that is every hash in the manifest; DEP-411 narrows it to the blobs the team does not hold.

Array<string>

project

Project is present on POST /uploads, which created it (DEP-671). It stays provisional (provisional_until set) until this upload, or a retry of it, publishes; if none ever does, the sweeper deletes it.

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

default_branch

string

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

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

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

project_id

ProjectID is the project the upload publishes to.

string

total_bytes_to_send

integer

upload_id

string

Example

{
  "data": {
    "project": {
      "created_client": "dashboard",
      "created_via": "session",
      "framework": "nextjs",
      "package_manager": "npm",
      "platform_url_mode": "redirect",
      "preview_branch_mode": "all",
      "status": "active"
    }
  }
}

400

Invalid request body or Idempotency-Key

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

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

PLAN_LIMIT_EXCEEDED: site limit reached, or the manifest exceeds the plan’s upload allowance

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

403

Team suspended

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

SUBDOMAIN_TAKEN with details.suggestions, or PROJECT_NAME_TAKEN

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

SUBDOMAIN_INVALID or SUBDOMAIN_RESERVED with details.suggestions; INVALID_MANIFEST; or not a publishable site (UPLOAD_SITE_IN_SUBFOLDER, UPLOAD_SOURCE_CODE, UPLOAD_PHP_SITE)

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

429

Too many upload sessions

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