Deploys

One publish, from asking for upload addresses to putting a version live. Versions are immutable and are never written over, so promoting an earlier one is a pointer moving rather than an upload repeating.

Validates a manifest and returns one presigned upload URL per file.

POST

https://dropto.run

/api/sites/{siteId}/deploys/prepare

d2r_session (cookie)

Bearer

X-Claim-Token (header)

Validates a manifest and returns one presigned upload URL per file. › path Parameters

siteId

string · required

Validates a manifest and returns one presigned upload URL per file. › Request Body

Request body of `POST /deploys/prepare`.

PrepareDeployRequest

ManifestEntry[] · minItems: 1 · required

Every file the client intends to upload.

batches

boolean

Whether the client can send batch permits — several small files in one request. A client that does not set it receives one permit per file. Setting it is a request, not a guarantee: the server may still answer with single permits only.

Default: false

Validates a manifest and returns one presigned upload URL per file. › Responses

Response of `POST /deploys/prepare`.

PrepareDeployResponse

UploadBatch[] · required

Batch permits, each covering several small files sent as one body. Empty unless the request asked for batches and they are enabled; a file is in exactly one of Upload and this.

deployId

string · required

ULID of the new deploy; part of every R2 key it writes.

reused

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

How many files the live deploy already holds byte-identical. These are absent from Upload and are copied server-side when the deploy completes.

total

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Files in the whole deploy: Reused plus what must be uploaded.

UploadTarget[] · required

One upload permit per file sent on its own.

uploadUrl

string · required

The single endpoint every permit is presented to. Sent with the response rather than compiled into the client, because it is a different host in development, in tests and in production — and because a client that knew the address without being told would still know it after we moved.

batchConcurrency

null | integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$

How many of Batches to send at once; null when there are none. The upload Worker can hold only six R2 writes open per request, so this is what decides how fast many small files go, and it is set here so it can be tuned without a client release. Single permits are not affected.

unchanged

boolean

True when the manifest describes exactly what is already live, so no deploy was created. The caller has nothing to upload and must not call complete: DeployId is the deploy already serving, and completing it again would only rewrite the mapping to where it already points.

Default: false

url

null | string

Public URL of the site, sent only when Unchanged is true. That answer is the end of the deploy, and without it the caller would have to ask a second endpoint just to show the link.

warnings

null | array

Things about this deploy the caller should be told although it was accepted, or null when there are none — today only that _functions/ will not run on this site (docs/briefs/FUNCTIONS-BRIEF.md D23).

POST/api/sites/{siteId}/deploys/prepare

curl https://dropto.run/api/sites/:siteId/deploys/prepare \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "batches": false,
  "files": [
    {
      "path": "path",
      "sha256": "sha256",
      "size": 0
    }
  ]
}'

Example Request Body

{
  "batches": false,
  "files": [
    {
      "path": "path",
      "sha256": "sha256",
      "size": 0
    }
  ]
}

json

Example Responses

{
  "batchConcurrency": 0,
  "batches": [
    {
      "files": [
        {
          "path": "path",
          "sha256": "sha256"
        }
      ],
      "token": "token"
    }
  ],
  "deployId": "deployId",
  "reused": 0,
  "total": 0,
  "unchanged": false,
  "upload": [
    {
      "path": "path",
      "sha256": "sha256",
      "token": "token"
    }
  ],
  "uploadUrl": "uploadUrl",
  "url": "url",
  "warnings": [
    "string"
  ]
}

json

application/json

Reads the state of one deploy.

GET

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}

d2r_session (cookie)

Bearer

X-Claim-Token (header)

Reads the state of one deploy. › path Parameters

siteId

string · required

deployId

string · required

Reads the state of one deploy. › Responses

Response of `GET /sites/{siteId}/deploys/{deployId}`.

DeployDetail

completedAt

null | string · date-time · required

When it reached a terminal state, or null while in flight.

createdAt

string · date-time · required

When it was prepared.

deployId

string · required

ULID of the deploy.

error

null | string · required

Why it failed, when it did.

fileCount

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Files it holds.

isLive

boolean · required

Whether this is the deploy currently being served.

siteId

string · required

ULID of its site.

status

string · required

Lowercase status name.

totalBytes

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Its size.

url

null | string · required

The site's URL, present only when this deploy is live.

Verifies the uploaded files and takes the deploy live.

POST

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}/complete

d2r_session (cookie)

Bearer

X-Claim-Token (header)

Verifies the uploaded files and takes the deploy live. › path Parameters

siteId

string · required

deployId

string · required

Verifies the uploaded files and takes the deploy live. › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = null
	type = object

Properties for Variant 1:

null

Verifies the uploaded files and takes the deploy live. › Responses

Response of `POST /deploys/{deployId}/complete`.

CompleteDeployResponse

deployId

string · required

ULID of the deploy that is now live.

docsMode

boolean · required

Whether the site is read through the documents viewer rather than served as files.

Reported for the same reason as Name: the server decides it, from the files this deploy actually holds (SiteModeDetection), and a client that guessed from what it uploaded would be wrong exactly when it matters — the web app that went live inside the reader because its index.html sat one folder too deep, with nothing on the finished card saying so.

edge

string · required

live when the edge has the deploy, pending when the deploy is live but the edge write did not land yet — Cloudflare refused it or its API budget is spent. A pending deploy is not a failure: it reaches the edge on its own, usually within the Retry-After the response carries, and calling complete again is safe but not needed.

fileCount

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Number of verified files.

modeIsManual

boolean · required

Whether the owner chose the mode by hand, in which case no deploy changes it.

name

null | string · required

What the site is called now, or null when it has none and its subdomain should be shown instead.

Reported rather than left for the client to infer, because only the server knows the answer: it cleans the name it is sent, and it refuses to overwrite a name the site already had. A client that assumed the title it sent is the name now stored would be wrong on every redeploy.

What the anonymous flow needs. A site is remembered in the browser before its first deploy starts — the claim token is returned once and storing it cannot wait — so the name is not known at that point and arrives here instead.

spaMode

boolean · required

Whether unmatched paths are answered with the site's index.html.

status

string · required

Always live on success.

totalBytes

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Total verified size in bytes.

url

string · required

Public URL the site answers on. Content may take up to a minute to reach every edge.

Reads one text file out of one deploy, for the in-browser editor.

GET

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}/file

d2r_session (cookie)

Bearer

Reads one text file out of one deploy, for the in-browser editor. › path Parameters

siteId

string · required

deployId

string · required

Reads one text file out of one deploy, for the in-browser editor. › query Parameters

path

string

Reads one text file out of one deploy, for the in-browser editor. › Responses

Response of `GET /sites/{siteId}/deploys/{deployId}/file`.

DeployFileContent

path

string · required

The path, normalized — which is the spelling the manifest holds.

sha256

string · required

Digest of the content as stored.

Sent so the editor can publish a change without re-reading anything: the new manifest is the old one with this entry's digest replaced, and every other file is reused by prepare.

size

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Size in bytes, as the manifest records it.

text

null | string · required

The file's text, or null when the bytes are not valid UTF-8.

Null rather than a lossy decode, so the dashboard can say the file cannot be edited here instead of offering an editor whose contents would overwrite the original with replacement characters.

Lists the files one deploy contains, a page at a time or all at once.

GET

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}/manifest

d2r_session (cookie)

Bearer

Lists the files one deploy contains, a page at a time or all at once. › path Parameters

siteId

string · required

deployId

string · required

Lists the files one deploy contains, a page at a time or all at once. › query Parameters

search

string

cursor

string

limit

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$

all

boolean

Default: false

Lists the files one deploy contains, a page at a time or all at once. › Responses

Response of `GET /sites/{siteId}/deploys/{deployId}/manifest`.

DeployManifestPage

deployId

string · required

ULID of the deploy the files belong to.

fileCount

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Files in the whole deploy, whatever the filter matched.

ManifestFile[] · required

This page of matches, ordered by path.

filesKept

boolean · required

Whether the deploy is inside the retention window with its objects still on storage, the same answer as filesKept on the site's version list. The list is answerable either way — it is read from the row — so this is what separates "these files are here" from "these files were here".

matchingBytes

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Their total size, on the same terms.

matchingFiles

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Files the filter matched, equal to FileCount without one.

nextCursor

null | string · required

Path to pass back as cursor for the following page, or null when this page was the last.

status

string · required

Lowercase status name of that deploy.

totalBytes

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Size of the whole deploy, whatever the filter matched.

Lets the in-browser editor's preview frame load a gated version's own files.

POST

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}/preview-ticket

d2r_session (cookie)

Bearer

Lets the in-browser editor's preview frame load a gated version's own files. › path Parameters

siteId

string · required

deployId

string · required

Lets the in-browser editor's preview frame load a gated version's own files. › Responses

Response of `POST /sites/{siteId}/deploys/{deployId}/preview-ticket`.

PreviewTicket

action

string · required

The URL to post the ticket to, as the form field ticket, targeting the preview frame.

expiresAt

string · date-time · required

When the frame's access runs out and a new ticket is needed.

ticket

string · required

The signed ticket. Accepted for one minute.

Rolls the site back to an earlier deploy that still has its files.

POST

https://dropto.run

/api/sites/{siteId}/deploys/{deployId}/promote

d2r_session (cookie)

Bearer

X-Claim-Token (header)

Rolls the site back to an earlier deploy that still has its files. › path Parameters

siteId

string · required

deployId

string · required

Rolls the site back to an earlier deploy that still has its files. › Responses

Response of `POST /sites/{siteId}/deploys/{deployId}/promote`.

PromoteDeployResponse

deployId

string · required

ULID of the deploy that is now live.

edge

string · required

live when the edge has the deploy, pending when the rollback is committed but the edge write did not land yet; it gets there on its own, as on complete.

fileCount

integer | string · int32 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Files in the promoted deploy.

status

string · required

Always live on success.

totalBytes

integer | string · int64 · pattern: ^-?(?:0|[1-9]\d*)$ · required

Its total size in bytes.

url

string · required

Public URL the site answers on. Content may take up to a minute to reach every edge.

Site folders Billing