Deploy & Alias Workflow

Create and manage deploys, then point an alias to a specific version for staged rollouts.

Press.js Cloud supports two deploy types:

• managed — uploaded artifacts create immutable deploy versions.
• url — render directly from a hosted targetUrl.

Create a deploy

Request: POST /v1/deploys

curl -X POST "$PRESS_CLOUD_API/v1/deploys" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-document",
    "name": "My Document"
  }'

Response: 201 Created

{
  "deploy": {
    "id": "dpl_abc123",
    "workspaceId": "ws_abc123",
    "slug": "my-document",
    "name": "My Document",
    "type": "managed",
    "createdAt": 1745800000000
  }
}

Next: After creation, upload artifacts via an upload session. The deploy is an empty shell until a version is committed.

Error handling: A 409 with deploy_slug_conflict means the slug is already in use. Choose a different slug.

Create a URL deploy

Request: POST /v1/deploys

curl -X POST "$PRESS_CLOUD_API/v1/deploys" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "hosted-document",
    "name": "Hosted Document",
    "type": "url",
    "targetUrl": "https://app.example.com/document"
  }'

Response: 201 Created

{
  "deploy": {
    "id": "dpl_url123",
    "workspaceId": "ws_abc123",
    "slug": "hosted-document",
    "name": "Hosted Document",
    "type": "url",
    "targetUrl": "https://app.example.com/document",
    "createdAt": 1745800000000
  }
}

URL deploys do not store deploy versions. Render jobs use deployVersionId: "latest" and snapshot the target URL at job creation time. See URL Deploys for the full hosted-target workflow.

Update a deploy

Request: PATCH /v1/deploys/{deployId}

curl -X PATCH "$PRESS_CLOUD_API/v1/deploys/dpl_abc123" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Renamed Document"
  }'

Response: 200 OK

{
  "deploy": {
    "id": "dpl_abc123",
    "workspaceId": "ws_abc123",
    "slug": "my-document",
    "name": "My Renamed Document",
    "type": "managed",
    "createdAt": 1745800000000
  }
}

For URL deploys, update the target URL with:

curl -X PATCH "$PRESS_CLOUD_API/v1/deploys/dpl_url123" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://app.example.com/document-v2"
  }'

Error handling: 404 if the deploy does not exist. 409 if the requested slug is already taken or targetUrl is used on a managed deploy.

List deploys

Request: GET /v1/deploys

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/deploys"

Response: 200 OK

{
  "items": [
    {
      "id": "dpl_abc123",
      "slug": "my-document",
      "name": "My Document",
      "type": "managed",
      "createdAt": 1745800000000
    }
  ]
}

Paginate with the cursor query parameter (see Cursor Pagination).

Point an alias to a version

Aliases (preview, production) let you route render jobs to specific versions without updating every caller.

Aliases apply to managed deploys. URL deploys render the configured target URL with the latest pointer.

Request: POST /v1/deploys/{deployId}/aliases/{alias}

curl -X POST "$PRESS_CLOUD_API/v1/deploys/dpl_abc123/aliases/production" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployVersionId": "dv_456"
  }'

The deployVersionId can be a concrete version ID or the virtual pointer latest.

Response: 200 OK

{
  "deployId": "dpl_abc123",
  "alias": "production",
  "deployVersionId": "dv_456",
  "updatedAt": 1745800100000
}

Next: Create a render job against this alias.

Error handling: 404 if the deploy or version does not exist. The alias is updated atomically — in-flight render jobs continue using the version they were created against.