Docs

Documentation

Pass Markdown via the content query param (URL-encoded), or swap in your own string in this file. GitHub-flavored Markdown is supported out of the box.

News API – Full Reference (EN)

Base URL defaults to 

https://newsapi.one/
. All application endpoints live under 
/v1/**
and use JSON.

Authentication & Security

  • API key required on every 
    /v1/**
    route except: 
    /v1/auth/**
    , 
    /v1/health/**
    , 
    /actuator/**
    , 
    /v1/test/public
    .
  • Preferred header: 
    X-API-KEY: <key>
    ; query fallback: 
    ?apiKey=<key>
    .
  • Failure: missing/invalid key → 
    401
    with body 
    Unauthorized: Missing or invalid API key
    .
  • Admin secret: 
    admin.api.key
    (application properties) required for admin-only endpoints below.

Response Conventions

  • All endpoints return 
    ApiResponse<T>
    : 
    • status
      : 
      ok
      | 
      error
    • message
      : string or null
    • data
      : payload or null
  • Paginated responses use 
    PaginatedResponse<T>
    inside 
    data
    : 
    • samples
      array, 
      totalItems
      , 
      totalPages
      , 
      currentPage
      (0-based), 
      pageSize
      .
  • Typical errors: 
    401
    (auth), 
    404
    (not found), 
    400
    (bad input/adminKey), 
    500
    (server error).

Data Models

  • Article (
    articles
    ): 
    id
    , 
    title
    , 
    url
    , 
    summary
    , 
    text
    , 
    source
    , 
    scraped_at
    (timestamp), 
    topic
    , 
    sentiment
    (
    label
    , 
    score
    ), 
    sample
    .
  • Event (
    events
    ): 
    id
    , 
    label
    , 
    summary
    , 
    category
    , 
    tags
    (array), 
    firstSeenAt
    , 
    lastSeenAt
    , 
    articleIds
    (array), 
    centroidEmbedding
    (number array), 
    importanceScore
    (int), 
    status
    , 
    sourceStats
    (map), 
    miscFlags
    (map).
  • PipelineLog (
    pipeline_logs
    ): 
    id
    , 
    ts
    (timestamp), 
    actor
    , 
    action
    , 
    articleId
    , 
    eventId
    , 
    status
    , 
    details
    (map), 
    errorMessage
    .
  • ApiKey (
    api_keys
    ): 
    id
    , 
    user
    , 
    key
    , 
    active
    .
  • RequestLog (
    request_logs
    ): 
    path
    , 
    method
    , 
    ip
    , 
    apiKey
    , 
    timestamp
    , 
    success
    , 
    statusCode
    , 
    errorMessage
    , 
    durationMillis
    .
  • RequestLogAnalyticsResponse<T> extends pagination with 
    successCount
    , 
    failureCount
    , 
    averageDurationMillis
    .

Endpoints

Auth & API Keys (public routes; some admin-gated)

  • Generate API key (admin-only): 
    • POST /v1/auth/generate-key?user=<name>&adminKey=<admin-secret>
    • 401
      if admin key is wrong.
    • Example:
    {
  "status": "ok",
  "message": null,
  "data": {
    "id": "665e2c4c9b1a2b3c4d5e6f70",
    "user": "demo-user",
    "key": "generated-api-key",
    "active": true
  }
}
  • API key logs (basic): 
    • GET /v1/auth/logs?apiKey=<key>&page=0
    • Returns 
      ApiResponse<PaginatedResponse<RequestLog>>
      with counts and average duration.
    • Example:
    {
  "status": "ok",
  "message": "This a list of the metrics of apiKey: demo",
  "data": {
    "samples": [
      {
        "path": "/v1/news",
        "method": "GET",
        "ip": "127.0.0.1",
        "apiKey": "demo",
        "timestamp": "2025-11-27T03:57:19.241",
        "success": true,
        "statusCode": 200,
        "errorMessage": null,
        "durationMillis": 42
      }
    ],
    "totalItems": 5,
    "totalPages": 1,
    "currentPage": 0,
    "pageSize": 10,
    "successCount": 4,
    "failureCount": 1,
    "averageDurationMillis": 37.4
  }
}
  • API key logs (filtered, admin-only): 
    • GET /v1/auth/logs/filtered?apiKey=<key>&page=0&adminKey=<admin-secret>&date=<yyyy-MM-dd>&success=<true|false>
    • 400
      if admin key is invalid.
    • Example:
    {
  "status": "ok",
  "message": "Filtered logs for apiKey: demo",
  "data": {
    "samples": [],
    "totalItems": 0,
    "totalPages": 0,
    "currentPage": 0,
    "pageSize": 10,
    "successCount": 0,
    "failureCount": 0,
    "averageDurationMillis": 0.0
  }
}

Articles (requires API key)

  • List articles: 
    GET /v1/news?page=0&size=10&sort=DESC
    • Example:
    {
  "status": "ok",
  "message": "Paginated news articles",
  "data": {
    "samples": [
      {
        "id": "6904354c432617e4cff52372",
        "title": "Market rallies...",
        "url": "https://example.com/article",
        "summary": "Short summary",
        "text": "Full text ...",
        "source": "Example News",
        "scraped_at": "2025-10-16T22:15:35.034+00:00",
        "topic": "business",
        "sentiment": {"label": "positive", "score": 0.82},
        "sample": "Excerpt..."
      }
    ],
    "totalItems": 123,
    "totalPages": 13,
    "currentPage": 0,
    "pageSize": 10
  }
}
  • By topic: 
    GET /v1/news/by-topic?value=<topic>&page=0&size=10&sort=DESC
  • By title (contains, case-insensitive): 
    GET /v1/news/by-title?value=<text>&page=0&size=10&sort=DESC
    • Example:
    {
  "status": "ok",
  "message": "Paginated news articles by title",
  "data": {
    "samples": [
      {
        "id": "6904354c432617e4cff52372",
        "title": "Market rallies on trade optimism",
        "url": "https://example.com/article",
        "summary": "Short summary",
        "text": "Full text ...",
        "source": "Example News",
        "scraped_at": "2025-10-16T22:15:35.034+00:00",
        "topic": "business",
        "sentiment": {"label": "positive", "score": 0.82},
        "sample": "Excerpt..."
      }
    ],
    "totalItems": 2,
    "totalPages": 1,
    "currentPage": 0,
    "pageSize": 10
  }
}
  • By scraped date: 
    GET /v1/news/by-date?value=<yyyy-MM-dd>&page=0&size=10&sort=DESC
    • Date must be 
      yyyy-MM-dd
      ; otherwise 
      400
      .
  • By id: 
    GET /v1/news/{id}
    → 
    404
    if missing.
    • Example:
    {
  "status": "ok",
  "message": "Article details",
  "data": {
    "id": "6904354c432617e4cff52372",
    "title": "Market rallies...",
    "url": "https://example.com/article",
    "summary": "Short summary",
    "text": "Full text ...",
    "source": "Example News",
    "scraped_at": "2025-10-16T22:15:35.034+00:00",
    "topic": "business",
    "sentiment": {"label": "positive", "score": 0.82},
    "sample": "Excerpt..."
  }
}
  • Sort: 
    ASC
    /
    DESC
    on 
    scrapedAt
    .

Events (requires API key; CRUD)

  • List: 
    GET /v1/events?page=0&size=10&sort=DESC
    • Example:
    {
  "status": "ok",
  "message": "Paginated events",
  "data": {
    "samples": [
      {
        "id": "6927b0b89dc428f8611c028f",
        "label": "Trump-Xi trade talks at APEC summit in South Korea, 2025",
        "summary": "In late October 2025...",
        "category": "politics",
        "tags": ["Donald Trump","Xi Jinping"],
        "firstSeenAt": "2025-10-16T22:15:35.034Z",
        "lastSeenAt": "2025-11-26T05:08:14.720Z",
        "articleIds": ["6904354c432617e4cff52372"],
        "centroidEmbedding": [-0.0059, 0.0102],
        "importanceScore": 23,
        "status": "active",
        "sourceStats": {"aljazeera": 1},
        "miscFlags": {"created_by": "clusterer"}
      }
    ],
    "totalItems": 1,
    "totalPages": 1,
    "currentPage": 0,
    "pageSize": 10
  }
}
  • By category: 
    GET /v1/events/by-category?value=<category>&page=0&size=10&sort=DESC
  • By firstSeenAt date: 
    GET /v1/events/by-date?value=<yyyy-MM-dd>&page=0&size=10&sort=DESC
  • By status: 
    GET /v1/events/by-status?value=<status>&page=0&size=10&sort=DESC
  • By id: 
    GET /v1/events/{id}
    → 
    404
    if missing.
    • Example:
    {
  "status": "ok",
  "message": "Event details",
  "data": {
    "id": "6927b0b89dc428f8611c028f",
    "label": "Trump-Xi trade talks at APEC summit in South Korea, 2025",
    "summary": "In late October 2025...",
    "category": "politics",
    "tags": ["Donald Trump","Xi Jinping"],
    "firstSeenAt": "2025-10-16T22:15:35.034Z",
    "lastSeenAt": "2025-11-26T05:08:14.720Z",
    "articleIds": ["6904354c432617e4cff52372"],
    "centroidEmbedding": [-0.0059, 0.0102],
    "importanceScore": 23,
    "status": "active",
    "sourceStats": {"aljazeera": 1},
    "miscFlags": {"created_by": "clusterer"}
  }
}
  • Create: 
    POST /v1/events
    • Example body:
    {
  "label": "Example label",
  "summary": "Summary",
  "category": "politics",
  "tags": ["tag1","tag2"],
  "firstSeenAt": "2025-10-16T22:15:35.034Z",
  "lastSeenAt": "2025-11-26T05:08:14.720Z",
  "articleIds": ["id1","id2"],
  "centroidEmbedding": [0.1, -0.2],
  "importanceScore": 10,
  "status": "active",
  "sourceStats": {"source": 1},
  "miscFlags": {"created_by": "manual"}
}
  • Update: 
    PUT /v1/events/{id}
    with same shape; 
    404
    if id missing.
  • Delete: 
    DELETE /v1/events/{id}
    ; 
    404
    if id missing.
  • Sort: 
    ASC
    /
    DESC
    on 
    firstSeenAt
    .
    • Example create/update response:
    {
  "status": "ok",
  "message": "Event created",
  "data": {
    "id": "6927b0b89dc428f8611c028f",
    "label": "Example label",
    "summary": "Summary",
    "category": "politics",
    "tags": ["tag1","tag2"],
    "firstSeenAt": "2025-10-16T22:15:35.034Z",
    "lastSeenAt": "2025-11-26T05:08:14.720Z",
    "articleIds": ["id1","id2"],
    "centroidEmbedding": [0.1, -0.2],
    "importanceScore": 10,
    "status": "active",
    "sourceStats": {"source": 1},
    "miscFlags": {"created_by": "manual"}
  }
}
    • Example delete response:
    {
  "status": "ok",
  "message": "Event deleted",
  "data": null
}

Pipeline Logs (requires API key)

  • List: 
    GET /v1/pipeline-logs?page=0&size=10&sort=DESC
    • Example:
    {
  "status": "ok",
  "message": "Paginated pipeline logs",
  "data": {
    "samples": [
      {
        "id": "6927cc073632780a90c56fd8",
        "ts": "2025-11-27T03:56:55.227Z",
        "actor": "online_assign",
        "action": "assign_article",
        "articleId": "69267f87253035c01db6e762",
        "eventId": "6927bb11a1e1197c9238d1ea",
        "status": "success",
        "details": {"similarity": 0.5351753231986613, "mode": "strict"},
        "errorMessage": null
      }
    ],
    "totalItems": 10,
    "totalPages": 1,
    "currentPage": 0,
    "pageSize": 10
  }
}
  • By actor: 
    GET /v1/pipeline-logs/by-actor?value=<actor>&page=0&size=10&sort=DESC
  • By action: 
    GET /v1/pipeline-logs/by-action?value=<action>&page=0&size=10&sort=DESC
  • By status: 
    GET /v1/pipeline-logs/by-status?value=<status>&page=0&size=10&sort=DESC
  • By article: 
    GET /v1/pipeline-logs/by-article?value=<articleId>&page=0&size=10&sort=DESC
  • By event: 
    GET /v1/pipeline-logs/by-event?value=<eventId>&page=0&size=10&sort=DESC
  • By date: 
    GET /v1/pipeline-logs/by-date?value=<yyyy-MM-dd>&page=0&size=10&sort=DESC
  • By id: 
    GET /v1/pipeline-logs/{id}
    → 
    404
    if missing.
  • Sort: 
    ASC
    /
    DESC
    on 
    ts
    .
    • Example get-by-id:
    {
  "status": "ok",
  "message": "Pipeline log details",
  "data": {
    "id": "6927cc073632780a90c56fd8",
    "ts": "2025-11-27T03:56:55.227Z",
    "actor": "online_assign",
    "action": "assign_article",
    "articleId": "69267f87253035c01db6e762",
    "eventId": "6927bb11a1e1197c9238d1ea",
    "status": "success",
    "details": {"similarity": 0.5351753231986613, "mode": "strict"},
    "errorMessage": null
  }
}

Health & Test

  • Health: 
    GET /v1/health
    (public) — composite health without diskSpace; 
    503
    if any component is down.
  • Test public: 
    GET /v1/test/public
    (public) — simple ping.
  • Test secured: 
    GET /v1/test/secured
    (API key) — echoes the authenticated apiKey.
    • Examples:
    {"status":"UP","details":{"mongo":{"status":"UP","details":{}}}}
    {"message":"Public endpoint reachable without API key"}
    {
  "message": "Secured endpoint reached with valid API key",
  "apiKeyUsed": "demo-key"
}

Common Problems & Troubleshooting

  • 401 Unauthorized: missing/invalid API key. Ensure header or query is set and the key is active.
  • 400 Bad Request: bad adminKey, malformed dates (
    yyyy-MM-dd
    ), wrong types (e.g., non-numeric 
    importanceScore
    ).
  • 404 Not Found: id absent for article/event/pipeline-log.
  • Empty pagination: requesting 
    page
    > 
    totalPages-1
    returns empty 
    samples
    .
  • Sorting: only 
    ASC
    or 
    DESC
    ; invalid falls back to 
    DESC
    .
  • Mongo validation: no explicit validation layer—provide required fields when creating events.
  • 500 Internal: check application logs; common causes are Mongo connectivity or malformed payloads.

Quick Testing Cheatsheet (swap 
API_KEY
)

  • Articles: 
    curl -H "X-API-KEY: API_KEY" "https://newsapi.one/v1/news?page=0&size=5"
  • Create event: 
    curl -X POST -H "X-API-KEY: API_KEY" -H "Content-Type: application/json" -d '{"label":"Test","summary":"s","status":"active"}' https://newsapi.one/v1/events
  • Pipeline logs by actor: 
    curl -H "X-API-KEY: API_KEY" "https://newsapi.one/v1/pipeline-logs/by-actor?value=online_assign"