Builder Guide

Build your BloGoose Blog API in one brief

One prompt covers planning, the API, storage, tests, and how to connect the finished site. Open it in Cursor, Claude Code, or another assistant.

Open API docs Jump to copy blocks

One handoff

The brief includes planning, the build, storage, the endpoint list, the full contract, and the test checklist.

Open in Cursor

Cursor opens with a link to the full brief and asks the assistant to implement it in the current project.

Open in Claude Code

Claude Code loads the full brief into a new session.

Other assistants

Claude, ChatGPT, Gemini, and VS Code Copilot get the same brief. The full text is also copied so you can paste it.

What the brief covers

The box below is the whole handoff: inspect the site, build the API, add storage, test it, and connect it to BloGoose.

Inspect + plan Build the API Add storage Test Connect to BloGoose

Fastest option

Open the brief in Cursor or Claude Code and let it inspect the project before it writes the API.

Best for Cursor

Use Open in Cursor. The chat starts with a link to this brief, and the full markdown is copied to your clipboard.

Best for owners

Send the same brief and ask for the connection steps in plain English. That part is already in the document.

Best for freelancers

The brief ends with the test checklist, so the delivery can be reviewed against the same list.

Blog API brief

Copy it, or open it in Cursor, Claude Code, or another assistant. The full brief is one document.

BloGoose Blog API

Inspect, build, store, test, and connect. Includes the endpoint list, the full contract, and the test checklist.

# Step 1 - Inspect My Current Website And Plan The Blog API

I want to connect my website to BloGoose.

Please inspect my current website/app structure and tell me the best way to add a BloGoose-compatible Blog API.

I need:

1. the best place to add the API route
2. what database tables or CMS fields I need
3. what files you will create or change
4. how preview URLs should work
5. how scheduling should work

The target API route is:

`POST /hey_api/v1/blog/access`

The API must support:

- create_post
- update_post
- accept_post
- get_post
- list_posts
- delete_post
- upload_image
- list_categories
- create_category

Please reply with:

- short implementation plan
- file structure
- schema/data model
- any assumptions you need from me

# Step 2 - Build The Blog API In My Existing App

Build a BloGoose-compatible Blog API inside my current codebase.

Use one endpoint:

`POST /hey_api/v1/blog/access`

Use an `action` field in the JSON body.

Please implement:

- create_post
- update_post
- accept_post
- get_post
- list_posts
- delete_post
- upload_image
- list_categories
- create_category

Authentication:

- X-API-Key
- X-Timestamp
- X-Signature

Signature:

`HMAC-SHA256(raw_json_body + timestamp, API_SECRET)`

Important fields to support:

- title
- content
- category_id
- status
- meta_title
- meta_description
- meta_keywords
- featured_image
- featured_image_alt
- og_image
- canonical_url
- author_name
- scheduled_at

Preview behavior:

- preview posts must return preview_url
- preview posts must not be publicly listed
- update_post must preserve preview_url while still in preview
- accept_post must publish now or schedule later
- accept_post must clear preview token

Please write the full implementation directly in my app and include setup notes.

# Step 3 - Add Database / CMS Storage Properly

Please add or update the database/CMS storage needed for the BloGoose Blog API.

Make sure posts can store:

- title
- slug
- content_html
- status
- preview_token
- category_id
- featured_image
- featured_image_alt
- meta_title
- meta_description
- meta_keywords
- og_image
- canonical_url
- author_name
- scheduled_at
- published_at
- details JSON
- created_at
- updated_at

Also make sure categories and uploaded images are supported.

Please give:

1. migration/schema
2. model/storage logic
3. any indexes needed
4. notes for preview and scheduled publishing

# Step 4 - Test The BloGoose Blog API

Please test the blog API you built for BloGoose.

Check all flows:

- valid auth works
- invalid auth is rejected
- create_post works
- preview_url is returned
- update_post works
- accept_post publishes now
- accept_post schedules future post
- upload_image works
- list_categories works
- list_posts works
- canonical_url is saved
- og_image is saved

Please give:

1. example curl commands
2. expected responses
3. final pass/fail checklist
4. any issues still remaining

# Step 5 - Tell Me How To Connect This To BloGoose

Now that the blog API is built, explain the final connection steps very simply.

Tell me:

1. what my Blog API Base URL should be
2. where to create my Blog API key
3. where to create my Blog API secret
4. what Website URL and Sitemap URL I should use
5. how to do one final end-to-end test

Write it for a non-technical owner in plain English.

# Things Needed To Make BloGoose Work Properly

Before BloGoose can work properly with a website, these things should be ready:

## 1. Website information

- Website URL
- Sitemap URL

These help BloGoose understand the site, detect the niche, avoid duplicate topics, and build better internal links.

## 2. Blog API connection

Your website must provide:

- Blog API endpoint
- Blog API key
- Blog API secret

BloGoose uses these to securely create previews, upload images, and publish posts.

## 3. AI access

Ogni is included with every BloGoose account. You do not create an AI account or paste a model key.

## Where it goes inside BloGoose

- Website URL + Sitemap URL → Onboarding or Autopilot
- Blog API Base URL + API Key + API Secret → Sites → Add Site (Connected Sites)

## Minimum setup for most users

The easiest working setup is:

1. Website URL
2. Sitemap URL
3. Blog API key + secret

That is enough for BloGoose to start detecting niche, planning topics, generating content, and sending posts to your site.

# Endpoints Needed For BloGoose To Connect Easily

If you want to build the easiest possible blog API for BloGoose, use one route:

`POST /hey_api/v1/blog/access`

Then support these actions inside the JSON body:

## Required actions

- `create_post` → create a preview or draft post
- `update_post` → update a preview/draft post
- `accept_post` → publish now or schedule for later
- `upload_image` → upload featured and content images
- `list_categories` → return available blog categories

## Recommended actions

- `get_post` → fetch one post
- `list_posts` → fetch existing posts and avoid duplicates
- `delete_post` → archive a post safely

## Optional action

- `create_category` → create a category if it does not already exist

## Easiest way to think about it

BloGoose only needs a few core abilities:

1. send article HTML
2. upload images
3. create a preview
4. update the preview
5. publish or schedule the post
6. read categories

If you build the required actions first, BloGoose can already work well with your website.

# BloGoose Blog API, Advanced Implementation Spec (For Any Code Builder)

Use this as the **single source of truth** when generating code in Cursor, Copilot, Windsurf, or hand-off to a human team.  
**Audience**: senior backend engineer. **Goal**: interoperate with BloGoose’s official client, which signs the **raw** JSON body.

---

## 1. Product context (why this exists)

BloGoose generates long-form HTML articles, images, and SEO metadata. It POSTs them to **your** CMS or custom database through **one** endpoint. Your implementation must support **preview → edit → publish/schedule** without leaking drafts to SEO surfaces.

---

## 2. Transport

| Item | Value |
|------|--------|
| Method | `POST` only |
| Path | `/hey_api/v1/blog/access` (exact suffix; reverse-proxy may strip prefix) |
| Content-Type | `application/json; charset=utf-8` |
| Body | Single JSON object; must include `"action": "<string>"` |

---

## 3. Authentication (HMAC), **most common bug**

**Verifier must use the raw HTTP body string**, byte-for-byte, concatenated with the **`X-Timestamp` header value as received** (string), then HMAC-SHA256 with the shared secret, output **lowercase hexadecimal**.

```
payload_to_sign = rawRequestBody + xTimestampHeaderValue
signature_hex   = HMAC_SHA256( api_secret, payload_to_sign )
```

**Do not**: parse JSON → re-serialize → sign. Different serializers (PHP `json_encode`, JS `JSON.stringify`, key ordering) will break signatures.

**Do**: in Express use `express.raw({ type: 'application/json' })` then verify on buffer, **or** use middleware that captures `req.body` as string before `JSON.parse`. In PHP, read `php://input` for verification, then `json_decode` separately.

**Headers (required on every call)**

- `X-API-Key`, public identifier (compare to configured allowlist).
- `X-Timestamp`, Unix time in **seconds**, decimal string (e.g. `"1713001234"`). BloGoose sends string.
- `X-Signature`, hex digest only, no `sha256=` prefix.

**Reject with 401** if: wrong key, skew > **300s**, malformed timestamp, signature mismatch, or missing headers.

**Do not log** full secrets, raw base64 images, or bearer tokens in production logs.

---

## 4. JSON request envelope

Top-level keys include `action` plus action-specific fields. Unknown keys: ignore or 400, pick one and document.

---

## 5. Actions, contract

### `create_post`

| Field | Req | Notes |
|-------|-----|--------|
| `action` | ✓ | `"create_post"` |
| `title` | ✓ | |
| `content` | ✓ | HTML fragment or full article HTML |
| `category_id` | ✓ | Integer ID in **your** system |
| `status` | | `"draft"` or `"preview"` (default `preview` for BloGoose) |
| `excerpt`, `featured_image`, `featured_image_alt`, `meta_title`, `meta_description`, `meta_keywords`, `og_image`, `canonical_url`, `author_name`, `author_title`, `scheduled_at`, `published_at`, `is_featured`, `is_noindex`, `details` | | Persist as applicable |

**Preview (`status: "preview"`)**: generate cryptographically strong `preview_token`; return absolute `preview_url` (https) that loads the post only with token (query or path, your choice, document it). Exclude from listings, sitemap, RSS, search index.

**Response `data` (example keys)**: `id`, `slug`, `preview_url`, `preview_token`, `status`.

### `update_post`

| Field | Req |
|-------|-----|
| `action` | ✓ |
| `id` **or** `slug` | one required |

Same updatable fields as create. If still preview, **keep the same** `preview_url` (and token unless you rotate intentionally, if you rotate, document).

### `accept_post`

| Field | Req |
|-------|-----|
| `action` | ✓ |
| `id` or `slug` | ✓ |
| `scheduled_at` | optional ISO8601 or your documented format; if future → scheduled, else publish now |

Clear `preview_token`; post becomes visible per your rules.

### `get_post`

`id` or `slug`. Return full record including meta fields.

### `list_posts`

Filters: `status`, `category_id`, `search`, `page` (default 1), `limit` (default 20, cap 100).  
Return `{ "data": [...], "pagination": { "total", "page", "limit" } }` inside outer `data` or flatten, **document**; BloGoose expects posts array + pagination object somewhere in response.

### `delete_post`

Soft-delete → status `archived` (or equivalent); never hard-delete if avoidable.

### `upload_image`

| Field | Req |
|-------|-----|
| `action` | ✓ |
| `image` | ✓ base64 (data URL prefix optional, strip `data:image/...;base64,`) |
| `post_id` | optional |
| `filename` | optional suggested name, such as `clothing-video-generator.webp` |
| `alt` | optional alt text from the post |
| `title` | optional media title from the post |

Validate type (png, jpeg, webp, gif) and max size (recommend **≤ 6MB** decoded). Return public **URL** in `data.file_path` or `data.url`, **document** field name; BloGoose looks for uploaded file path/URL in response.

`filename`, `alt`, and `title` are optional. Older clients omit them. Sanitize `filename` to a single path segment, derive the extension from the detected MIME type (never from the client name), and make the stored name unique (`-2`, `-3`, …). Ignore `alt` and `title` if the platform has nowhere to store them.

### `list_categories`

Return id + name (+ count optional).

### `create_category`

`name` required; optional `description`, `sort_order`, `status`. Return new `id`.

---

## 6. Response envelope (mandatory)

Success:

```json
{ "success": true, "message": "string", "data": { } }
```

Failure:

```json
{ "success": false, "message": "human readable" }
```

Use HTTP **401** auth, **400** validation, **404** missing resource, **413** payload too large, **415** wrong content type, **422** business rule.

---

## 7. HTML & SEO

- Store HTML as UTF-8. Allow semantic tags: `p`, `h2`, `h3`, `ul`, `ol`, `li`, `strong`, `em`, `a`, `img`, `blockquote`, `figure`, etc.
- Sanitize **only** what you must for XSS; do not strip `href` on internal links or `img src` to BloGoose-uploaded assets.
- Persist `canonical_url` and `og_image` verbatim when provided. If `og_image` empty, fallback to `featured_image` on read is OK.

---

## 8. Security checklist

- [ ] HMAC on **raw body** + header timestamp  
- [ ] Constant-time signature compare  
- [ ] Rate limit this route (per IP + per key)  
- [ ] Base64 decode size cap; virus scan optional  
- [ ] Preview tokens unguessable; HTTPS only in production  
- [ ] No secrets in logs or error messages  

---

## 9. Deliverables

1. Runnable code + file tree  
2. Migration/schema or meta-key map  
3. `.env` template  
4. **curl** script covering happy path + 3 failure paths  
5. README: Base URL for BloGoose “Blog API Base URL”, where keys are set  

Implement first: auth + `create_post` preview + `upload_image` + `accept_post` + `list_categories`. Then the rest.

# BloGoose Blog API - Testing Checklist

Please test every flow below:

## Authentication

- valid API key works
- invalid API key is rejected
- invalid signature is rejected
- stale timestamp is rejected

## Posts

- create draft works
- create preview returns preview_url
- update preview works
- accept preview publishes immediately
- accept preview schedules future post
- get single post works
- list posts works with filters
- delete archives post

## Images

- upload base64 image works
- featured image saves correctly
- `og_image` saves correctly

## SEO fields

- `meta_title` saved
- `meta_description` saved
- `meta_keywords` saved
- `featured_image_alt` saved
- `canonical_url` saved
- `og_image` saved

## Preview behavior

- preview URL loads correctly
- preview is not publicly listed
- preview token is cleared after accept_post

## Final output

Give me:

1. passing test summary
2. example request and response for each action
3. any remaining edge cases

Need the exact API contract too?

The main docs page explains every request field, auth header, and response format in detail.

Open API Docs View Pricing