# NewsPro API Overview

## Authentication

Include your API token in every request:

```
POST https://yoursite.newspro.io/functions/api
Content-Type: application/json
Authorization: Bearer YOUR_SECRET_KEY
```

Find your token in: **Dashboard → Settings → API**
The API must be enabled in your dashboard settings.

## Request Format

Every request is a JSON POST body with at minimum `resource` and `action`:

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

| Field | Required | Description |
|---|---|---|
| `resource` | Yes | One of: `article`, `category`, `page`, `breaking`, `user`, `media` |
| `action` | Yes | One of: `get`, `add`, `edit`, `delete` (media has additional actions) |
| `id` | No | Operate on a single record by ID |
| `fields` | No | Array of field names to return. Omit to return all fields |
| `filters` | No | Object of filter conditions (varies per resource) |
| `limit` | No | Number of results (default: 50, max: 100) |
| `offset` | No | Pagination offset (default: 0) |
| `order_by` | No | e.g. `"created_at DESC"` or `"title ASC"` |

## Response Format

Success:
```json
{ "status": "success", "data": { ... } }
```

Error:
```json
{ "status": "error", "message": "Description of the error" }
```

## Available Resources

- [Articles](https://newspro.io/docs/api/articles.md)
- [Categories](https://newspro.io/docs/api/categories.md)
- [Pages](https://newspro.io/docs/api/pages.md)
- [Breaking News](https://newspro.io/docs/api/breaking.md)
- [Users](https://newspro.io/docs/api/users.md)
- [Media](https://newspro.io/docs/api/media.md)

---

# 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
}
```

---

# Categories API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Category ID |
| `title` | string | Category name |
| `slug` | string | URL slug (auto-generated if empty) |
| `description` | string | Short description of the category |
| `color` | string | Hex color for the category label/badge (e.g. `#FF5733`) |
| `parent_id` | int | Parent category ID (`0` = top-level) |
| `category_top` | int | `1` = show in top navigation bar, `0` = hide |
| `top_menu_position` | int | Sort order in top navigation (lower number = first) |
| `hamburger_menu_position` | int | Sort order in mobile/hamburger menu |
| `user_id` | int | ID of the user who created the category |
| `approved` | int | `1` = approved, `0` = pending review |
| `status` | int | `1` = Private, `2` = Registered only, `3` = Public |
| `total_views` | int | View count |
| `created_at` | datetime | Creation date |
| `updated_at` | datetime | Last update date |

---

## Get All Categories

```json
{
  "resource": "category",
  "action": "get",
  "filters": {
    "parent_id": 0,
    "status": 3,
    "approved": 1,
    "search": "science"
  },
  "fields": ["id", "title", "slug", "color", "category_top", "top_menu_position", "status"],
  "limit": 20,
  "offset": 0,
  "order_by": "top_menu_position ASC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in title and slug |
| `parent_id` | `0` = top-level categories only |
| `status` | `1` = Private, `2` = Registered only, `3` = Public |
| `approved` | `1` = approved only |

---

## Get Single Category

```json
{
  "resource": "category",
  "action": "get",
  "id": 2
}
```

---

## Add Category

```json
{
  "resource": "category",
  "action": "add",
  "title": "Technology",
  "slug": "technology",
  "color": "#FF5733",
  "description": "Tech news and updates",
  "category_top": 1,
  "top_menu_position": 5,
  "hamburger_menu_position": 1,
  "user_id": 1,
  "parent_id": 0,
  "approved": 1,
  "status": 3
}
```

| Field | Required | Notes |
|---|---|---|
| `title` | Yes | Category name |
| `slug` | No | Auto-generated if empty. No spaces allowed |
| `color` | No | Hex color for badge/label |
| `description` | No | Short description |
| `category_top` | No | `1` = show in top nav, `0` = hide |
| `top_menu_position` | No | Sort order in top nav (lower = first) |
| `hamburger_menu_position` | No | Sort order in mobile menu |
| `user_id` | Yes | ID of the user creating the category |
| `parent_id` | No | `0` = top-level, or ID of parent category |
| `approved` | No | `1` = approved, `0` = pending |
| `status` | No | `1` = Private, `2` = Registered only, `3` = Public |

---

## Edit Category

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

```json
{
  "resource": "category",
  "action": "edit",
  "id": 116,
  "title": "Tech & Science",
  "slug": "tech-science",
  "color": "#00FF00",
  "description": "Updated description",
  "category_top": 1,
  "top_menu_position": 2,
  "hamburger_menu_position": 2,
  "parent_id": 0,
  "approved": 1,
  "status": 3
}
```

---

## Delete Category

```json
{
  "resource": "category",
  "action": "delete",
  "id": 121
}
```

> Note: Deleting a category moves all its articles to the default category and detaches any sub-categories.

---

# Pages API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Page ID |
| `title` | string | Page title (shown in navigation and browser tab) |
| `slug` | string | URL path (e.g. `/page/about-us`) |
| `description` | string | Short summary used for SEO meta description |
| `content` | string | Full page HTML content (supports dynamic blocks) |
| `thumbnail` | int | Media file ID for page cover image |
| `status` | int | `1` = published/visible, `0` = hidden |
| `total_views` | int | View count |
| `created_at` | datetime | Creation date |
| `updated_at` | datetime | Last update date |

---

## Embedding Media in Content

The `content` field supports the same rich editor as articles. 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 Pages

```json
{
  "resource": "page",
  "action": "get",
  "filters": {
    "status": 1,
    "search": "about"
  },
  "fields": ["id", "title", "slug", "status", "created_at"],
  "limit": 20,
  "offset": 0,
  "order_by": "created_at DESC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in title and slug |
| `status` | `1` = published, `0` = hidden |

---

## Get Single Page

```json
{
  "resource": "page",
  "action": "get",
  "id": 1
}
```

---

## Add Page

```json
{
  "resource": "page",
  "action": "add",
  "title": "About Us",
  "slug": "about-us",
  "description": "Learn more about our editorial team",
  "content": "<h2>Who We Are</h2><p>Body HTML...</p><dynamic-block data-id=\"15\" data-type=\"media\" data-size=\"large\" contenteditable=\"false\"></dynamic-block>",
  "status": 1,
  "thumbnail": 20
}
```

| Field | Required | Notes |
|---|---|---|
| `title` | Yes | Page title |
| `slug` | No | Auto-generated if empty. No spaces allowed |
| `description` | No | SEO meta description |
| `content` | No | Full HTML content. Supports dynamic blocks (see above) |
| `thumbnail` | No | Media file ID for cover image |
| `status` | No | `1` = published, `0` = hidden |

---

## Edit Page

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

```json
{
  "resource": "page",
  "action": "edit",
  "id": 5,
  "title": "About Us - Updated",
  "slug": "about-us",
  "description": "Updated SEO description",
  "content": "<h2>Updated heading</h2><p>Updated body...</p>",
  "thumbnail": 10,
  "status": 1
}
```

> Note: The default homepage (ID 1) cannot be edited or deleted via API.

---

## Delete Page

```json
{
  "resource": "page",
  "action": "delete",
  "id": 5
}
```

---

# Breaking News API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Breaking news item ID |
| `user_id` | int | ID of the user who published the item |
| `title` | string | Short headline shown in the breaking news ticker |
| `content` | string | Additional details or body text |
| `status` | int | `1` = active (shown in ticker), `0` = inactive (hidden) |
| `created_at` | datetime | Creation date |

---

## Get All Breaking News

```json
{
  "resource": "breaking",
  "action": "get",
  "filters": {
    "user_id": 1,
    "status": 1,
    "date_from": "2025-01-01",
    "date_to": "2025-12-31"
  },
  "fields": ["id", "user_id", "title", "content", "status", "created_at"],
  "limit": 20,
  "offset": 0,
  "order_by": "created_at DESC"
}
```

| Filter | Description |
|---|---|
| `user_id` | Filter by author user ID |
| `status` | `1` = active only, `0` = inactive only |
| `date_from` | Items from this date (`YYYY-MM-DD`) |
| `date_to` | Items up to this date (`YYYY-MM-DD`) |

---

## Get Single Breaking News Item

```json
{
  "resource": "breaking",
  "action": "get",
  "id": 1
}
```

---

## Add Breaking News

```json
{
  "resource": "breaking",
  "action": "add",
  "user_id": 1,
  "title": "Breaking: Major event happening now",
  "content": "Additional details or source URL",
  "status": 1
}
```

| Field | Required | Notes |
|---|---|---|
| `user_id` | Yes | ID of the publishing user |
| `title` | Yes | Headline shown in the ticker |
| `content` | No | Extra details or a URL |
| `status` | No | `1` = active (visible), `0` = inactive (hidden). Default: `0` |

---

## Edit Breaking News

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

```json
{
  "resource": "breaking",
  "action": "edit",
  "id": 1,
  "title": "Updated headline",
  "content": "Updated content",
  "status": 1
}
```

---

## Delete Breaking News

```json
{
  "resource": "breaking",
  "action": "delete",
  "id": 1
}
```

---

# Users API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `user_id` | int | User ID |
| `username` | string | Unique username (min 4 chars, lowercase, no spaces) |
| `email` | string | Unique email address |
| `firstname` | string | First name |
| `lastname` | string | Last name |
| `biography` | string | Short bio shown on author profile page |
| `avatar` | string | Avatar image URL (200×200) |
| `avatar_small` | string | Small avatar URL (50×50, auto-generated) |
| `user_role` | int | Role ID — see your user roles in Dashboard → Settings → Users |
| `language` | string | UI language code (e.g. `en-US`, `he-IL`, `fr-FR`) |
| `account_suspended` | int | `0` = active, `1` = suspended (blocked from login) |
| `email_alerts` | int | `1` = receives email notifications, `0` = off |
| `device_alerts` | int | `1` = receives push notifications, `0` = off |
| `public_key` | string | Public identifier |
| `link_website` | string | Personal website URL |
| `link_facebook` | string | Facebook profile URL |
| `link_x` | string | X (Twitter) profile URL |
| `link_instagram` | string | Instagram profile URL |
| `link_youtube` | string | YouTube channel URL |
| `link_twitch` | string | Twitch channel URL |
| `link_linkedin` | string | LinkedIn profile URL |
| `total_views` | int | Total article views across all authored articles |
| `created_at` | datetime | Registration date |
| `updated_at` | datetime | Last update date |

---

## Get All Users

```json
{
  "resource": "user",
  "action": "get",
  "filters": {
    "user_role": 2,
    "account_suspended": 0,
    "language": "en-US",
    "search": "john"
  },
  "fields": ["user_id", "username", "email", "firstname", "lastname", "user_role", "created_at"],
  "limit": 20,
  "offset": 0,
  "order_by": "created_at DESC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in username, firstname, lastname, email |
| `user_role` | Filter by role ID |
| `account_suspended` | `0` = active only, `1` = suspended only |
| `language` | Filter by language code (e.g. `en-US`) |

---

## Get Single User

```json
{
  "resource": "user",
  "action": "get",
  "id": 3
}
```

---

## Add User

```json
{
  "resource": "user",
  "action": "add",
  "firstname": "John",
  "lastname": "Doe",
  "username": "johndoe",
  "email": "john@example.com",
  "user_role": 2,
  "language": "en-US",
  "account_suspended": 0,
  "avatar": "https://example.com/avatar.jpg",
  "biography": "Senior reporter covering international affairs",
  "link_website": "https://johndoe.com",
  "link_facebook": "https://facebook.com/johndoe",
  "link_x": "https://x.com/johndoe",
  "link_instagram": "https://instagram.com/johndoe",
  "link_youtube": "https://youtube.com/johndoe",
  "link_twitch": "https://twitch.tv/johndoe",
  "link_linkedin": "https://linkedin.com/in/johndoe",
  "email_alerts": 1,
  "device_alerts": 1
}
```

| Field | Required | Notes |
|---|---|---|
| `firstname` | Yes | User's first name |
| `lastname` | No | User's last name |
| `username` | Yes | Unique, min 4 chars, lowercase, no spaces |
| `email` | Yes | Unique email address |
| `user_role` | Yes | Role ID from Dashboard → Settings → Users |
| `language` | No | Language code. Default: `en-US` |
| `account_suspended` | No | `0` = active, `1` = suspended. Default: `0` |
| `avatar` | No | Public image URL — downloaded and resized to 200×200 automatically |
| `biography` | No | Short bio for author profile |
| `link_*` | No | Social/website profile URLs |
| `email_alerts` | No | `1` = on, `0` = off |
| `device_alerts` | No | `1` = on, `0` = off |

---

## Edit User

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

```json
{
  "resource": "user",
  "action": "edit",
  "user_id": 3,
  "firstname": "John Updated",
  "lastname": "Doe",
  "username": "johndoe_updated",
  "email": "newemail@example.com",
  "biography": "Updated bio",
  "avatar": "https://example.com/new-avatar.jpg",
  "user_role": 2,
  "language": "en-US",
  "account_suspended": 0,
  "email_alerts": 1,
  "device_alerts": 1,
  "link_website": "https://johndoe.com",
  "link_facebook": "https://facebook.com/johndoe",
  "link_x": "https://x.com/johndoe",
  "link_instagram": "https://instagram.com/johndoe",
  "link_youtube": "https://youtube.com/johndoe",
  "link_twitch": "https://twitch.tv/johndoe",
  "link_linkedin": "https://linkedin.com/in/johndoe"
}
```

---

## Delete User

```json
{
  "resource": "user",
  "action": "delete",
  "user_id": 3
}
```

---

# Media API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Media file ID |
| `file_name` | string | File name |
| `file_path` | string | Full path or CDN URL to the file |
| `file_type` | string | MIME type (e.g. `image/jpeg`, `image/png`, `video/mp4`, `audio/mpeg`) |
| `file_size` | string | Human-readable file size (e.g. `245 KB`) |
| `resolution` | string | Image resolution (e.g. `1920x1080`) |
| `title` | string | Display title shown in media library |
| `credit` | string | Photo/video credit or source attribution |
| `description` | string | Internal notes or alt text description |
| `cache_versions` | json | Cached size variants (304px, 500px, 800px WebP) |
| `created_at` | datetime | Upload date |

---

## Using Media in Articles and Pages

After uploading a file, use its `id` to:
- Set as article **thumbnail**: `"thumbnail": 15`
- Set as article **video**: `"video_link": 5`
- Set as article **audio/TTS**: `"audio_tts_id": 47`
- Embed **inline** in `body` or `content` via dynamic block:

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

---

## Get All Media

```json
{
  "resource": "media",
  "action": "get",
  "filters": {
    "file_type": "image/jpeg",
    "search": "banner",
    "date_from": "2025-01-01",
    "date_to": "2025-12-31"
  },
  "fields": ["id", "file_name", "file_path", "file_type", "file_size", "resolution", "title", "created_at"],
  "limit": 20,
  "offset": 0,
  "order_by": "id DESC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in file name, title, description |
| `file_type` | MIME type (e.g. `image/jpeg`, `image/png`, `video/mp4`) |
| `date_from` | Files uploaded from this date (`YYYY-MM-DD`) |
| `date_to` | Files uploaded up to this date (`YYYY-MM-DD`) |

---

## Get Single Media File

```json
{
  "resource": "media",
  "action": "get",
  "id": 123
}
```

---

## Upload from URL

Downloads a file from a public URL and imports it into the media library. Returns the new media `id` to use in articles/pages.

```json
{
  "resource": "media",
  "action": "upload_from_url",
  "file_url": "https://example.com/image.jpg"
}
```

Supports: images (JPG, PNG, WebP, GIF), video, and audio files.

**Response:**
```json
{
  "status": "success",
  "files": [[{ "id": "48", "file_path": "...", "file_type": "image/jpeg", ... }]]
}
```

---

## Update Metadata

```json
{
  "resource": "media",
  "action": "update_metadata",
  "file_id": 123,
  "title": "Photo title",
  "credit": "Photographer Name / Agency",
  "description": "Photo description or alt text"
}
```

---

## Delete Media

Deletes the file and all its cached size variants.

```json
{
  "resource": "media",
  "action": "delete",
  "file_id": 123
}
```

---

## Create Cache Versions

Regenerates all image cache sizes (304px, 500px, 800px WebP) for every file in the library.

```json
{
  "resource": "media",
  "action": "create_all_cache"
}
```

---

## Delete Cache Versions

Removes all cached size variants for all media files (original files are kept).

```json
{
  "resource": "media",
  "action": "delete_all_cache"
}
```