# Articles API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Article ID |
| `title` | string | Article headline |
| `slug` | string | URL slug (auto-generated from title if empty) |
| `subtitle` | string | Short description shown below the title |
| `body` | string | Full article content (HTML, supports dynamic blocks) |
| `keywords` | string | Comma-separated keywords for SEO and search |
| `related_stocks` | string | Comma-separated stock ticker symbols (e.g. `AAPL, TSLA`) |
| `type_id` | int | Article type ID (e.g. 1=News, 2=Opinion) |
| `category_id` | int | Category ID |
| `country_id` | int | Country ID for geo-filtering |
| `user_id` | int | Author user ID |
| `additional_editors` | string | Comma-separated editor emails or usernames |
| `created_at` | datetime | Publication date (`YYYY-MM-DD HH:MM:SS`) |
| `updated_at` | datetime | Last update date |
| `total_views` | int | View count |
| `comments` | int | `1` = comments enabled, `0` = disabled |
| `total_comments` | int | Total comment count |
| `approved` | int | `1` = approved, `0` = pending review |
| `status` | int | `1` = Private, `2` = Registered users only, `3` = Public |
| `thumbnail` | int | Media file ID for the thumbnail image |
| `video_link` | int | Media file ID of a video file |
| `audio_tts_id` | int | Media file ID of an audio/TTS file |
| `display_article_home` | int | `1` = show on homepage, `0` = hide |
| `sponsored` | int | `1` = sponsored content, `0` = regular |
| `votes` | int | `1` = voting enabled, `0` = disabled |
| `credits` | string | Credits text or HTML shown at end of article (supports dynamic blocks) |
| `likes` | int | Like count |
| `dislikes` | int | Dislike count |
| `anonymous` | int | `1` = hide author identity, `0` = show author |

---

## Embedding Media in Body

The `body` and `credits` fields support the same rich editor as the dashboard. To embed images, videos, or audio inline, use dynamic blocks:

```html
<dynamic-block data-id="MEDIA_ID" data-type="media" data-size="large" contenteditable="false"></dynamic-block>
```

- `MEDIA_ID` = the numeric ID of the file in the media library (returned by `media` → `upload_from_url`)
- `data-size` options: `small`, `medium`, `large`
- Works for images, videos, and audio files — same syntax for all three

---

## Get All Articles

```json
{
  "resource": "article",
  "action": "get",
  "filters": {
    "category_id": 2,
    "country_id": 5,
    "user_id": 1,
    "approved": 1,
    "status": 3,
    "anonymous": 0,
    "date_from": "2025-01-01",
    "date_to": "2025-12-31",
    "search": "keyword"
  },
  "fields": ["id", "title", "slug", "category_id", "created_at", "status"],
  "limit": 20,
  "offset": 0,
  "order_by": "created_at DESC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in title, slug, subtitle, keywords |
| `date_from` | Articles created from this date (`YYYY-MM-DD`) |
| `date_to` | Articles created up to this date (`YYYY-MM-DD`) |
| `category_id` | Filter by category |
| `country_id` | Filter by country |
| `user_id` | Filter by author |
| `approved` | `1` = approved only |
| `status` | `1` = Private, `2` = Registered only, `3` = Public |
| `anonymous` | `1` = anonymous only, `0` = non-anonymous |

---

## Get Single Article

```json
{
  "resource": "article",
  "action": "get",
  "id": 18
}
```

---

## Add Article

```json
{
  "resource": "article",
  "action": "add",
  "title": "Article Title",
  "slug": "",
  "subtitle": "Subtitle text",
  "body": "<p>Article content HTML...</p><dynamic-block data-id=\"15\" data-type=\"media\" data-size=\"large\" contenteditable=\"false\"></dynamic-block>",
  "keywords": "news, article",
  "created_at": "2025-01-15 10:00:00",
  "type_id": 2,
  "category_id": 2,
  "country_id": 5,
  "user_id": 1,
  "additional_editors": "jane@example.com, john_doe",
  "approved": 1,
  "status": 3,
  "thumbnail": 15,
  "video_link": 5,
  "audio_tts_id": 47,
  "related_stocks": "AAPL, TSLA",
  "comments": 1,
  "display_article_home": 1,
  "sponsored": 0,
  "votes": 1,
  "credits": "",
  "anonymous": 0
}
```

| Field | Required | Notes |
|---|---|---|
| `title` | Yes | Article headline |
| `slug` | No | Auto-generated from title if empty |
| `subtitle` | No | Short description |
| `body` | Yes | HTML content. Embed media via dynamic blocks (see above) |
| `keywords` | No | Comma-separated SEO keywords |
| `created_at` | No | Defaults to now |
| `type_id` | No | Article type ID |
| `category_id` | Yes | Must be a valid category ID |
| `country_id` | No | Country ID |
| `user_id` | Yes | Author user ID |
| `additional_editors` | No | Comma-separated emails **or** usernames |
| `approved` | No | `1` = approved, `0` = pending |
| `status` | No | `1` = Private, `2` = Registered only, `3` = Public |
| `thumbnail` | No | Media file ID |
| `video_link` | No | Media file ID of a video |
| `audio_tts_id` | No | Media file ID of an audio/TTS file |
| `related_stocks` | No | Comma-separated ticker symbols |
| `comments` | No | `1` = on, `0` = off |
| `display_article_home` | No | `1` = show on homepage |
| `sponsored` | No | `1` = sponsored content |
| `votes` | No | `1` = voting enabled |
| `credits` | No | Credits text or HTML |
| `anonymous` | No | `1` = hide author |

---

## Edit Article

All fields are optional except `id`. Only fields included in the request are updated.

```json
{
  "resource": "article",
  "action": "edit",
  "id": 595,
  "title": "Updated Title",
  "subtitle": "Updated subtitle",
  "body": "<p>Updated content</p>",
  "slug": "updated-slug",
  "keywords": "update, news",
  "type_id": 2,
  "category_id": 2,
  "country_id": 5,
  "user_id": 1,
  "additional_editors": "jane@example.com, john_doe",
  "approved": 1,
  "status": 3,
  "thumbnail": 20,
  "video_link": 5,
  "audio_tts_id": 47,
  "related_stocks": "AAPL, TSLA",
  "comments": 1,
  "display_article_home": 1,
  "sponsored": 1,
  "votes": 1,
  "credits": "Photo: Reuters",
  "anonymous": 0
}
```

---

## Delete Article

```json
{
  "resource": "article",
  "action": "delete",
  "id": 608
}
```