# mBlog Write API (v1)

Base URL: `https://mblog.in/api/v1`

All **write** endpoints require an API key sent as a header:

```
X-API-Key: mbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Create a key on the server (prints once, store it safely):

```bash
php scripts/make_api_key.php "My Publisher"
```

Responses are JSON: `{ "success": true, "message": "...", "data": {...} }`.
Validation errors return HTTP 422 with `data`/`errors` describing the fields.

---

## 1. Upload an image  →  `POST /media`

`multipart/form-data` with a single field **`image`**. The server optimises it
for the web (resizes to max 1600px wide and re-encodes to WebP) so the stored
file is **≤ 100 KB**, then returns the **full URL**.

```bash
curl -X POST https://mblog.in/api/v1/media \
  -H "X-API-Key: $KEY" \
  -F "image=@/path/to/photo.jpg"
```

Response:

```json
{
  "success": true,
  "data": {
    "url":  "https://mblog.in/images/20260707-9f1c….webp",
    "path": "/images/20260707-9f1c….webp",
    "mime": "image/webp",
    "width": 1600, "height": 900, "size": 84213
  }
}
```

Use the returned `url` as `featured_image_url` (posts) or `image_url` (story parts).

---

## 2. Create a post  →  `POST /posts`

Works for **normal** and **story** posts. `Content-Type: application/json`.

Common fields:

| field                | required | notes |
|----------------------|----------|-------|
| `headline`           | yes      | ≤ 300 chars |
| `summary`            | yes      | 60–100 words (plain text or light HTML) |
| `featured_image_url` | yes      | full URL (from `/media`) |
| `category_id` **or** `category_slug` | yes | e.g. `"knowledge"` |
| `post_by`            | no       | author name (defaults to the API client) |
| `status`            | no       | `published` (default) / `draft` |
| `slug`, `seo_title`, `seo_description`, `canonical_url`, `published_at` | no | |

### Normal post
`source_url` is **required** (where "read more →" points). `content` is optional
on-site HTML.

```bash
curl -X POST https://mblog.in/api/v1/posts \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "headline": "125 new GI tags added",
    "summary": "India added 125 new GI tags ... (60–100 words)",
    "featured_image_url": "https://mblog.in/images/20260707-….webp",
    "category_slug": "knowledge",
    "source_url": "https://example.com/full-article",
    "content": "<p>Full on-site article HTML …</p>"
  }'
```

### Story post
Set `post_type: "story"` and provide `story_parts` (at least one). `source_url`
is optional. Each part: `{ heading?, html?, image_url? }` (needs html or image_url).

```bash
curl -X POST https://mblog.in/api/v1/posts \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "headline": "आज का GK : Quick points",
    "summary": "Short teaser used for SEO + the first slide … (60–100 words)",
    "featured_image_url": "https://mblog.in/images/cover.webp",
    "category_slug": "knowledge",
    "post_type": "story",
    "story_parts": [
      { "heading": "GI Tags", "html": "<p>… <b>822</b> total …</p>", "image_url": "https://mblog.in/images/p1.webp" },
      { "heading": "OPEC+",   "html": "<p>…</p>", "image_url": "https://mblog.in/images/p2.webp" }
    ]
  }'
```

The post itself is slide 1 (featured image + summary); each `story_parts` entry
becomes the next swipeable slide.

---

## 3. Add a part to an existing story  →  `POST /posts/{id}/parts`

Appends one slide to the end. If the post wasn’t a story yet, it becomes one.

```bash
curl -X POST https://mblog.in/api/v1/posts/123/parts \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "heading": "Part 3", "html": "<p>Next slide …</p>", "image_url": "https://mblog.in/images/p3.webp" }'
```

(`content` is accepted as an alias for `html`.)

---

## 4. Update / delete

- `PUT /posts/{id}` — same body as create. Only the fields you send change;
  omit `story_parts`/`post_type` to leave the story untouched.
- `DELETE /posts/{id}` — soft-deletes (hidden from the feed and API).

---

## Reads (no key needed)

`GET /posts`, `GET /posts/{slug}`, `GET /posts/{slug}/related`,
`GET /categories`, `GET /categories/{slug}`, `GET /search?q=…`, `GET /config`.
Post objects include `post_type` and `story_parts` (array of `{heading, html, image_url}`).