Compute publishing API

​

Goal

​

Prerequisites

• An authenticated StackShift customer session or token with access to the target VPS.
• An account with Compute publishing enabled. The API returns unavailable when the feature is disabled for the caller.

​

Workflow

​

Base paths and web routes

• GET /compute/features and GET /compute/instances/{instanceID}/publishing-availability determine whether the account can use Publishing.
• GET /compute/instances/{instanceID}/publications lists active web publications.
• POST /compute/instances/{instanceID}/publications creates a route with slug, target_port, and optional allowed_cidrs. The response contains publication; creation is initially pending.
• PATCH /compute/instances/{instanceID}/publications/{publicationID} changes target_port and allowed_cidrs. The hostname label does not change on update.
• DELETE /compute/instances/{instanceID}/publications/{publicationID} begins unpublishing and removes its attached custom domains.

{
  "slug": "myapp",
  "target_port": 3000,
  "allowed_cidrs": []
}

​

Custom-domain routes

• GET /compute/instances/{instanceID}/publications/{publicationID}/domains lists the route’s domains and their verification_name and verification_token.
• POST /compute/instances/{instanceID}/publications/{publicationID}/domains with {“hostname”:“app.example.com”} adds a domain in pending verification state.
• POST /compute/instances/{instanceID}/publications/{publicationID}/domains/{domainID}/verify checks TXT ownership and direct edge A/AAAA answers before activating the domain.
• DELETE /compute/instances/{instanceID}/publications/{publicationID}/domains/{domainID} removes the domain route.

​

Edge SSH routes

• GET /compute/instances/{instanceID}/publication-ssh returns ssh: null if disabled, or the assigned hostname, edge_port, target_port, username, allowed_cidrs, and status.
• PUT /compute/instances/{instanceID}/publication-ssh enables or updates the endpoint using target_port and optional allowed_cidrs. Re-enabling the same VPS retains its assigned external port.
• DELETE /compute/instances/{instanceID}/publication-ssh begins disabling the endpoint. Guest SSH remains unchanged.

{
  "target_port": 22,
  "allowed_cidrs": ["203.0.113.0/24"]
}

​

Validation and state

• Ports must be between 1 and 65535. CIDRs must parse as IP prefixes; at most 20 entries are accepted per route. The web slug must be a valid lowercase hostname label and cannot use a reserved StackShift label.
• Route status is pending, configured, or offline. Web health is separately unknown, healthy, or unhealthy. Configured describes applied infrastructure, while health describes a base-path HTTP probe.
• HTTP 400 indicates invalid input, 409 indicates a reserved hostname, limit, ineligible VPS, or incomplete DNS verification, and 503 indicates publishing is unavailable to the caller. Normal authentication and owner checks also apply.

​

Expected result

​

Related guides