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

# Native Ghost API reference

> Automate native Ghost creation, operation polling, actions, domains, recovery, staging, upgrades, and mail through the authenticated StackShift API.

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

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

<Steps>
  <Step>
    List runtime options and select a returned exact version.
  </Step>

  <Step>
    Create a site and retain the project and operation IDs from the HTTP 202 response.
  </Step>

  <Step>
    Poll the project-scoped operation endpoint until completed or failed.
  </Step>

  <Step>
    Use the project endpoints for lifecycle, domain, recovery, staging, upgrade, and mail changes.
  </Step>

  <Step>
    Treat all secrets as write-only and never log them.
  </Step>
</Steps>

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

```bash Create a hosted Ghost site theme={null}
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}'
```

```json Connected-node request body theme={null}
{
  "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

```json HTTP 202 data theme={null}
{
  "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

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

## Common failures

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

## Related guides

<CardGroup cols={2}>
  <Card title="Native Ghost hosting overview" href="/ghost/native-ghost-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.
  </Card>

  <Card title="Ghost recovery points and restore" href="/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.
  </Card>

  <Card title="Ghost troubleshooting and limitations" href="/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.
  </Card>
</CardGroup>