Native Ghost API reference

Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

Goal

Use the Ghost API without bypassing the curated runtime catalog or durable lifecycle operations.

Prerequisites

A StackShift API bearer token
Native Ghost enabled in the target environment
Project access for reads and mutation permission for writes

Workflow

List runtime options and select a returned exact version.

Create a site and retain the project and operation IDs from the HTTP 202 response.

Poll the project-scoped operation endpoint until completed or failed.

Use the project endpoints for lifecycle, domain, recovery, staging, upgrade, and mail changes.

Treat all secrets as write-only and never log them.

Response envelope and asynchronous operations

Examples below show the value inside StackShift’s standard data response envelope. Creation, backup, restore, staging, and upgrade return HTTP 202 with an operation. Poll that exact operation instead of assuming the resource is ready when the request returns.

Runtime and creation endpoints

GET /api/v1/ghost/runtime-options — list tested versions, labels, images, digests, database requirements, memory floor, default selection, and upgrade predecessors.
POST /api/v1/ghost/sites — create a fresh native Ghost project and enqueue provisioning.

Create a hosted Ghost site

curl -X POST "https://api.stackshift.cloud/api/v1/ghost/sites" \
  -H "Authorization: Bearer $STACKSHIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Journal","ghost_version":"6.57.1","deployment_mode":"hosted","mail_enabled":true}'

Connected-node request body

{
  "name": "Acme Journal",
  "ghost_version": "6.57.1",
  "deployment_mode": "connected_node",
  "target_node_id": "NODE_UUID",
  "placement_mode": "manual",
  "node_selector_tags": ["region:ng-lagos"],
  "mail_enabled": true
}

Create response

HTTP 202 data

{
  "project": { "id": "PROJECT_UUID", "source_type": "ghost", "runtime": "ghost" },
  "site_url": "https://acme-journal.example.stackshift.cloud",
  "admin_url": "https://acme-journal.example.stackshift.cloud/ghost/",
  "operation": {
    "id": "OPERATION_UUID",
    "resource_type": "ghost",
    "operation_type": "provision",
    "status": "pending",
    "step": "queued"
  }
}

Project read and action endpoints

GET /api/v1/ghost/projects/{projectID}/metadata — installation, project, managed database summary, active operation state, and mail flags.
GET /api/v1/ghost/projects/{projectID}/history — latest active operation state plus recovery points.
GET /api/v1/ghost/projects/{projectID}/operations/{operationID} — full durable operation.
POST /api/v1/ghost/projects/{projectID}/actions — body {"action":"restart"}, start, stop, or retry_provisioning.
POST /api/v1/ghost/projects/{projectID}/domain — body {"domain":"publication.example.com"}.

Recovery, staging, and upgrade endpoints

GET /api/v1/ghost/projects/{projectID}/recovery-points — list points newest first.
POST /api/v1/ghost/projects/{projectID}/recovery-points — optional body {"reason":"before-theme-change"}; returns the point and operation.
POST /api/v1/ghost/projects/{projectID}/recovery-points/{recoveryPointID}/restore — enqueue restore of a completed point.
POST /api/v1/ghost/projects/{projectID}/staging — optional body {"name":"Acme Journal QA"}; returns the source recovery point and staging operation.
POST /api/v1/ghost/projects/{projectID}/upgrades — body {"target_version":"6.57.1"}; validates the catalog edge and creates the pre-upgrade recovery record.

Mail endpoints

GET /api/v1/ghost/projects/{projectID}/mail/sender — safe transactional and Mailgun status.
PUT /api/v1/ghost/projects/{projectID}/mail/sender — body {"sender_email":"news@verified.example"}.
GET /api/v1/ghost/projects/{projectID}/mail/mailgun — same secret-safe mail settings view.
PUT /api/v1/ghost/projects/{projectID}/mail/mailgun — body fields: domain, region, api_key, from_email, and optional from_name.
DELETE /api/v1/ghost/projects/{projectID}/mail/mailgun — remove newsletter mapping and encrypted provider configuration.

Errors and status codes

202 Accepted means durable work was queued; it does not mean Ghost is already healthy.
400 Bad Request covers unsupported versions, invalid domains, invalid actions, incomplete recovery points, and unsupported upgrade paths.
401 Unauthorized means the bearer token is missing or invalid.
404 Not Found also protects resource ownership by not revealing inaccessible Ghost projects.
402 Payment Required is used for hosted plan or resource-limit gates.
When native Ghost is disabled, runtime options and Ghost operations return not found.

Expected result

Automation creates and operates Ghost through first-class APIs while preserving plan gates, capacity checks, ownership, digest enforcement, recovery safety, and secret handling.

Common failures

Hard-coding a version that is no longer returned by runtime-options.
Discarding the operation ID from a 202 response.
Polling metadata only and missing the operation’s detailed last error.
Logging Mailgun API keys or treating safe GET responses as secret backups.
Attempting a write with read-only team access.

Native Ghost hosting overview

How StackShift runs Ghost as a first-class native runtime with a pinned official image, managed MySQL 8, persistent content, plan-aware isolation, integrated mail, and durable lifecycle operations.

Ghost recovery points and restore

Capture Ghost’s MySQL data, persistent content, and exact runtime release as one coordinated recovery point, then restore the complete set through a durable operation.

Ghost troubleshooting and limitations

Diagnose native Ghost provisioning, database, image, routing, mail, recovery, staging, and upgrade failures using persisted operation state and clear resource boundaries.

​Goal

​Prerequisites

​Workflow

​Response envelope and asynchronous operations

​Runtime and creation endpoints

​Create response

​Project read and action endpoints

​Recovery, staging, and upgrade endpoints

​Mail endpoints

​Errors and status codes

​Expected result

​Common failures

​Related guides

Native Ghost hosting overview

Ghost recovery points and restore

Ghost troubleshooting and limitations

Goal

Prerequisites

Workflow

Response envelope and asynchronous operations

Runtime and creation endpoints

Create response

Project read and action endpoints

Recovery, staging, and upgrade endpoints

Mail endpoints

Errors and status codes

Expected result

Common failures

Related guides