# Ghost

## Ghost CMS Integration

Connect Cuppa to your Ghost blog to automatically publish AI-generated articles directly to your site. No manual copy-pasting required.

### What You Can Do

* **Auto-publish articles** to Ghost as they're generated
* **Publish as draft or live** — you choose the default
* **Featured images** are automatically uploaded
* **SEO metadata** is included (excerpts, slugs)

***

### Prerequisites

Before connecting, you'll need:

1. A **Ghost blog** (self-hosted or Ghost Pro)
2. **Admin access** to your Ghost site
3. Your Ghost site URL

***

### Step 1: Create a Custom Integration in Ghost

1. Log in to your **Ghost Admin** panel
2. Go to **Settings** → **Integrations**
3. Scroll down and click **"+ Add custom integration"**
4. Name it something like "Cuppa AI"
5. Click **Create**

You'll now see your integration details, including:

* **Content API Key** (not needed)
* **Admin API Key** ← This is what you need!

> 💡 **Tip**: The Admin API Key looks like: `abc123def456:789xyz...` (two parts separated by a colon)

***

### Step 2: Connect Ghost in Cuppa

1. Go to **Site Settings** → **Integrations**
2. Find **Ghost** and click **Connect**
3. Enter your:
   * **Ghost Site URL** (e.g., `https://myblog.ghost.io` or `https://blog.mysite.com`)
   * **Admin API Key** (the full key including the colon)
4. Click **Connect**

Cuppa will verify the connection before saving.

***

### Step 3: Configure Publishing Settings

After connecting, click **Settings** on your Ghost integration to configure:

#### Auto-Publishing

* **Enable**: Articles are automatically published to Ghost when generation completes
* **Disable**: Articles are only published when you manually trigger it

#### Default Post Status

* **Draft**: Articles are saved as drafts (recommended for review)
* **Published**: Articles go live immediately

***

### How It Works

#### When Auto-Publish is ON:

1. You generate an article in Cuppa
2. Cuppa automatically sends it to Ghost
3. The article appears in Ghost with your default status (draft or published)

#### When Auto-Publish is OFF:

1. Generate your article in Cuppa
2. Review and edit as needed
3. Click "Publish to Ghost" when ready

***

### What Gets Published

| From Cuppa     | To Ghost            |
| -------------- | ------------------- |
| Title          | Post title          |
| Content        | Post content (HTML) |
| Slug           | URL slug            |
| Excerpt        | Custom excerpt      |
| Featured Image | Feature image       |

***

### Troubleshooting

#### "Connection failed" error

**Check your Ghost URL:**

* Include `https://` at the start
* Don't include a trailing slash
* Use your actual Ghost URL, not a redirect
* Example: `https://myblog.ghost.io` (correct) vs `https://myblog.ghost.io/` (wrong)

**Check your Admin API Key:**

* Copy the entire key (it has two parts separated by `:`)
* Make sure there are no extra spaces
* The key format should be: `[id]:[secret]`
* Example: `64ab12cd34ef56gh:abcdef1234567890abcdef1234567890`

**Self-hosted Ghost issues:**

* Ensure your Ghost instance is accessible from the internet
* Check if your server firewall allows incoming connections
* Verify SSL certificate is valid (not self-signed)
* Check that your Ghost URL resolves correctly

#### "Authentication failed" error

* Your Admin API Key may have expired or been regenerated
* Go to Ghost Admin → Settings → Integrations → Your integration
* Copy a fresh Admin API Key
* If using Ghost Pro, ensure your subscription is active

#### "Rate limit exceeded" error

* Ghost limits API requests (varies by plan)
* Ghost Pro: Generally 100-500 requests per minute
* Self-hosted: Configurable but defaults are strict
* Wait a few minutes and try again, or space out bulk operations

#### "Post creation failed" error

**Content validation issues:**

* Ghost has a maximum post size (varies by hosting)
* HTML content must be well-formed
* Certain HTML tags may not be supported

**Title issues:**

* Post titles have a character limit (255 chars)
* Empty titles are not allowed
* Special characters may cause issues

#### Articles not appearing in Ghost

* Check if they're saved as drafts (look in Drafts, not Published)
* Verify your Ghost site is accessible
* Check the article's status in Cuppa (integration tab)
* Clear Ghost's cache if using a CDN

#### Featured images not showing

* Ghost requires images to be publicly accessible URLs
* Very large images (>10MB) may fail to upload
* Check that your Ghost site has storage available
* Supported formats: JPEG, PNG, GIF, WebP
* Ghost Pro has storage limits based on your plan

#### CORS / Cross-Origin errors

* If self-hosting, ensure your Ghost config allows the Cuppa domain
* Check your reverse proxy (nginx/Apache) settings
* Add Cuppa domains to your allowed origins

#### SSL / Certificate errors

* Ensure your SSL certificate is valid and not expired
* Self-signed certificates are not supported
* If using Cloudflare, ensure SSL mode is "Full (Strict)"

***

### Best Practices

#### Use Draft Mode First

When starting out, set your default status to "Draft." This lets you review AI-generated content before it goes live.

#### One Site = One Ghost Connection

Each Cuppa site connects to one Ghost blog. If you have multiple Ghost blogs, create separate sites in Cuppa.

#### Check Your Ghost Theme

Ensure your Ghost theme displays:

* Custom excerpts (for your SEO descriptions)
* Featured images
* Proper formatting for the HTML content

***

### FAQ

**Can I connect multiple Ghost blogs?** Each Cuppa site can connect to one Ghost blog. Create additional sites in Cuppa for additional Ghost blogs.

**Will it update existing posts?** Currently, Cuppa creates new posts. It doesn't update existing posts in Ghost. To update, delete the post in Ghost and republish from Cuppa.

**Does it support Ghost membership/paywall content?** Posts are created as public by default. You can change visibility settings directly in Ghost after publishing.

**What Ghost version is supported?** Cuppa works with Ghost 5.x and later (Admin API v5). Ghost 4.x may work but is not officially supported.

**Can I schedule posts?** Posts are published or saved as drafts immediately. Use Ghost's built-in scheduling feature to schedule posts after they're created.

**Does it work with Ghost Pro?** Yes! Cuppa works with both Ghost Pro (hosted) and self-hosted Ghost installations.

**What happens if my Ghost site is down?** If Ghost is temporarily unavailable, the publish attempt will fail. You can retry publishing from the article's integration tab in Cuppa.

**Are tags and categories supported?** Currently, Cuppa doesn't set tags or categories automatically. You can add these in Ghost after publishing.

**Can I publish to multiple Ghost sites at once?** No. Each Cuppa site connects to one Ghost blog. For multiple Ghost sites, create separate Cuppa sites.

**Does it support Ghost newsletters?** Posts are created as standard blog posts. Newsletter distribution settings must be configured in Ghost after the post is created.

**What about custom post templates?** Posts use Ghost's default post template. Custom templates can be selected in Ghost after publishing.

**Is there an API rate limit?** Yes. Ghost has rate limits that vary by hosting provider. Ghost Pro limits are generally 100-500 requests per minute. For bulk publishing, Cuppa handles rate limiting automatically.

**My images aren't being uploaded — why?**

* Check image URLs are publicly accessible
* Verify image size is under 10MB
* Ensure your Ghost plan has available storage
* Supported formats: JPEG, PNG, GIF, WebP

***

### Disconnecting

To disconnect Ghost:

1. Go to **Site Settings** → **Integrations**
2. Click **Settings** on your Ghost integration
3. Scroll down and click **Disconnect**

This removes the connection from Cuppa. Your existing posts in Ghost remain unchanged.

***

### Need Help?

* Check our [Help Center](https://learn.cuppa.ai)
* Contact support at <support@cuppa.ai>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/integrations/ghost.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.