> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Compute publishing API

> Authenticated routes, request fields, response status, and common errors for managing web publications, domains, and Edge SSH.

## Goal

Automate the same per-VPS publishing actions available in the Compute Publishing tab.

## 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

<Steps>
  <Step>
    Get Compute features and the instance publishing-availability response.
  </Step>

  <Step>
    Create a web publication or enable Edge SSH for the selected instance.
  </Step>

  <Step>
    Poll the corresponding read endpoint until status is configured, then test the guest service through the edge.
  </Step>
</Steps>

## Base paths and web routes

All paths below are under /api/v1 and require normal customer authentication. Replace \{instanceID}, \{publicationID}, and \{domainID} with IDs from your account. The availability endpoint returns enabled plus edge\_ipv4 and edge\_ipv6 values used by the custom-domain UI.

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

```json Create web publication body theme={null}
{
  "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.

```json Enable Edge SSH body theme={null}
{
  "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

<Check>
  The API returns the desired publication and exposes whether both the host and edge have applied it.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Connect with Edge SSH" href="/compute/edge-ssh">
    Enable a per-VPS SSH port on the StackShift edge and connect with your existing guest login and private key.
  </Card>

  <Card title="Publish a VPS web app" href="/compute/web-publishing">
    Map a StackShift HTTPS hostname to one selected HTTP port on a full-root Compute VPS.
  </Card>

  <Card title="Attach a custom domain" href="/compute/custom-domains">
    Prove ownership with DNS TXT, point A or AAAA directly at the edge, and attach the hostname to an existing web publication.
  </Card>
</CardGroup>