---
title: "Retrieve news items for display in clients."
method: GET
path: "/api/v1/news"
---

# Retrieve news items for display in clients.

`GET /api/v1/news`

**Authentication**: Optional (provides role-based filtering if authenticated)
**Purpose**: Fetch news and announcements for the QGIS plugin, web app, or API UI

**Query Parameters**:
- `platform`: Filter by platform (app, webapp, api-ui)
- `version`: Filter by plugin version compatibility
- `lang`: Language code for translations (e.g., 'es', 'fr', 'zh')
- `sort`: Sort field (prefix with '-' for descending)
- `page`: Page number for pagination (default: 1)
- `per_page`: Items per page (1-100, default: 20)

**Response Schema**:
```json
{
  "data": [
    {
      "id": "uuid-string",
      "title": "New Feature Available",
      "message": "We've released a new analysis tool...",
      "link_url": "https://docs.trends.earth/new-feature",
      "link_text": "Learn more",
      "created_at": "2025-01-15T10:30:00Z",
      "publish_at": "2025-01-15T10:30:00Z",
      "expires_at": null,
      "target_platforms": ["app", "webapp"],
      "target_roles": ["USER", "ADMIN"],
      "min_version": "2.0.0",
      "max_version": null,
      "priority": 10,
      "news_type": "info"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 5
}
```

**News Types**:
- `info`: General information or announcements
- `warning`: Important warnings or notices
- `alert`: Critical alerts requiring attention
- `update`: Software update notifications

**Platform Filtering**:
- `app`: QGIS plugin
- `webapp`: Web application
- `api-ui`: API admin UI

**Role Filtering**:
- News items can be targeted to specific roles (USER, ADMIN, SUPERADMIN)
- Unauthenticated users only see news with no role restrictions
- Authenticated users see news targeted to their role or with no restrictions

**Version Filtering**:
- News items can specify min_version and/or max_version
- Use semantic versioning (e.g., "2.1.0")

**Note**: Dismissal of news items is handled client-side (localStorage/QgsSettings).

## Response `200`

Success

- object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/trends/apis/trends-earth-api.md) · [All operations](https://skmtc.dev/trends/apis/trends-earth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trends/trends-earth-api/revisions/6bdbc0b84666/schema)