[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Blog

Manage your website blog articles. Create, update, schedule and delete posts, set their category, tags, author, summary and HTML content, and link related articles. List and read endpoints include drafts and scheduled posts; the public website only shows published articles whose publish time has passed.

## The Blog Object

Generated from the OpenAPI schema. Always matches the live API.

**Fields (14)**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | integer | - |  | `412` |
| `url` | string | - | URL slug (unique within the business). | `choosing-your-first-ev` |
| `title` | string | - |  | `Choosing your first EV` |
| `category` | string | - |  | `Buying Guides` |
| `author` | string | - |  | `Jane Doe` |
| `status` | enum | - | draft, published (live), or scheduled (published with a future publish time). | `published` |
| `tags` | array of string | - |  | `["EV","Buying Guide"]` |
| `published_at` | integer | - | Publish date/time as a unix timestamp. A future value with status published means scheduled. | `1781265600` |
| `summary` | string | - | HTML summary (full view only). |  |
| `summary_image` | string | - | Summary image URL (full view only). |  |
| `summary_thumbnail` | string | - | Summary thumbnail URL (full view only). |  |
| `content` | string | - | HTML article body (full view only). |  |
| `related` | array of integer | - | Related article ids (full view only). |  |
| `site` | integer | - | Website/site id (full view only). |  |

**Example object**

```json
{
    "id": 412,
    "url": "choosing-your-first-ev",
    "title": "Choosing your first EV",
    "category": "Buying Guides",
    "author": "Jane Doe",
    "status": "published",
    "tags": [
        "EV",
        "Buying Guide"
    ],
    "published_at": 1781265600,
    "summary": "",
    "summary_image": "",
    "summary_thumbnail": "",
    "content": "",
    "related": [
        0
    ],
    "site": 0
}
```

## Endpoints

### GET List Blog Articles

`GET /2.0/blogs` · scope `blogs:read`

List website blog articles with pagination and optional filters (status, category, author, tag, url).

**Parameters (10)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | - | Page number, starting at 1 (offset pagination). |  |
| `per_page` | query | integer | - | Results per page (maximum 500). |  |
| `view` | query | enum | - | simple (default for lists) or full (includes summary, content, related). |  |
| `status` | query | enum | - | Filter by publication status. | `published` |
| `category` | query | string | - | Filter by category. Exact match, or use % for wildcard matching (minimum 3 characters). | `Buying Guides` |
| `author` | query | string | - | Filter by author. Exact match, or use % for wildcard matching (minimum 3 characters). | `Jane Doe` |
| `tag` | query | string | - | Filter to articles tagged with this value. | `EV` |
| `url` | query | string | - | Filter by exact url slug. | `choosing-your-first-ev` |
| `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Paginated blog articles |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": [
        {
            "id": 412,
            "url": "choosing-your-first-ev",
            "title": "Choosing your first EV",
            "category": "Buying Guides",
            "author": "Jane Doe",
            "status": "published",
            "tags": [
                "EV",
                "Buying Guide"
            ],
            "published_at": 1781265600,
            "summary": "",
            "summary_image": "",
            "summary_thumbnail": "",
            "content": "",
            "related": [
                0
            ],
            "site": 0
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}
```

### POST Create Blog Article

`POST /2.0/blogs` · scope `blogs:write`

Create a website blog article. A title is required; the url slug is derived from the title when not supplied.

**Request body**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `title` | string | - | Article title (required on create). | `Choosing your first EV` |
| `url` | string | - | URL slug (lowercase letters, numbers and hyphens). Unique within the business; derived from the title when omitted on create. | `choosing-your-first-ev` |
| `category` | string | - | Category name (free text). | `Buying Guides` |
| `author` | string | - | Display name of the article author. | `Jane Doe` |
| `tags` | array of string | - | Tags/keywords. | `["EV","Buying Guide"]` |
| `summary` | string | - | HTML summary. Sanitised to an allow-list of safe tags. | `<p>A short guide to going electric.</p>` |
| `summary_image` | string | - | Summary image URL. | `https://cdn.example.com/blog/ev.jpg` |
| `summary_thumbnail` | string | - | Summary thumbnail URL. |  |
| `content` | string | - | HTML article body. Sanitised to an allow-list of safe tags. | `<h2>Range</h2><p>...</p>` |
| `related` | array of integer | - | Related article ids (must exist in this business). | `[401,402]` |
| `status` | enum | - | draft or published. A published article with a future published_at is treated as scheduled. | `published` |
| `published_at` | integer | - | Publish date/time as a unix timestamp. Defaults to now on create. A future value publishes the article on schedule. | `1781265600` |

```json
{
    "title": "Choosing your first EV",
    "url": "choosing-your-first-ev",
    "category": "Buying Guides",
    "author": "Jane Doe",
    "tags": [
        "EV",
        "Buying Guide"
    ],
    "summary": "<p>A short guide to going electric.</p>",
    "summary_image": "https://cdn.example.com/blog/ev.jpg",
    "summary_thumbnail": "",
    "content": "<h2>Range</h2><p>...</p>",
    "related": [
        401,
        402
    ],
    "status": "published",
    "published_at": 1781265600
}
```

**Responses**

| Status | Description |
| --- | --- |
| `201` Created | Blog article created |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 412,
        "url": "choosing-your-first-ev",
        "title": "Choosing your first EV",
        "category": "Buying Guides",
        "author": "Jane Doe",
        "status": "published",
        "tags": [
            "EV",
            "Buying Guide"
        ],
        "published_at": 1781265600,
        "summary": "",
        "summary_image": "",
        "summary_thumbnail": "",
        "content": "",
        "related": [
            0
        ],
        "site": 0
    }
}
```

### GET Get Blog Article

`GET /2.0/blogs/{id}` · scope `blogs:read`

Retrieve a single blog article by id (includes drafts and scheduled articles).

**Parameters (2)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Get Blog Article |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 412,
        "url": "choosing-your-first-ev",
        "title": "Choosing your first EV",
        "category": "Buying Guides",
        "author": "Jane Doe",
        "status": "published",
        "tags": [
            "EV",
            "Buying Guide"
        ],
        "published_at": 1781265600,
        "summary": "",
        "summary_image": "",
        "summary_thumbnail": "",
        "content": "",
        "related": [
            0
        ],
        "site": 0
    }
}
```

### PATCH Update Blog Article

`PATCH /2.0/blogs/{id}` · scope `blogs:write`

Update a blog article. Only the supplied fields are changed.

**Parameters (1)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |

**Request body**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `title` | string | - | Article title (required on create). | `Choosing your first EV` |
| `url` | string | - | URL slug (lowercase letters, numbers and hyphens). Unique within the business; derived from the title when omitted on create. | `choosing-your-first-ev` |
| `category` | string | - | Category name (free text). | `Buying Guides` |
| `author` | string | - | Display name of the article author. | `Jane Doe` |
| `tags` | array of string | - | Tags/keywords. | `["EV","Buying Guide"]` |
| `summary` | string | - | HTML summary. Sanitised to an allow-list of safe tags. | `<p>A short guide to going electric.</p>` |
| `summary_image` | string | - | Summary image URL. | `https://cdn.example.com/blog/ev.jpg` |
| `summary_thumbnail` | string | - | Summary thumbnail URL. |  |
| `content` | string | - | HTML article body. Sanitised to an allow-list of safe tags. | `<h2>Range</h2><p>...</p>` |
| `related` | array of integer | - | Related article ids (must exist in this business). | `[401,402]` |
| `status` | enum | - | draft or published. A published article with a future published_at is treated as scheduled. | `published` |
| `published_at` | integer | - | Publish date/time as a unix timestamp. Defaults to now on create. A future value publishes the article on schedule. | `1781265600` |

```json
{
    "title": "Choosing your first EV",
    "url": "choosing-your-first-ev",
    "category": "Buying Guides",
    "author": "Jane Doe",
    "tags": [
        "EV",
        "Buying Guide"
    ],
    "summary": "<p>A short guide to going electric.</p>",
    "summary_image": "https://cdn.example.com/blog/ev.jpg",
    "summary_thumbnail": "",
    "content": "<h2>Range</h2><p>...</p>",
    "related": [
        401,
        402
    ],
    "status": "published",
    "published_at": 1781265600
}
```

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Update Blog Article |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 412,
        "url": "choosing-your-first-ev",
        "title": "Choosing your first EV",
        "category": "Buying Guides",
        "author": "Jane Doe",
        "status": "published",
        "tags": [
            "EV",
            "Buying Guide"
        ],
        "published_at": 1781265600,
        "summary": "",
        "summary_image": "",
        "summary_thumbnail": "",
        "content": "",
        "related": [
            0
        ],
        "site": 0
    }
}
```

### DELETE Delete Blog Article

`DELETE /2.0/blogs/{id}` · scope `blogs:delete`

Delete a blog article.

**Parameters (1)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Delete Blog Article |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}
```