Back to jourai.app API Reference v1.0

JourAI API Docs.

The JourAI platform allows you to programmatically access content from your organization's newsroom infrastructure. Integrate automated monitoring, detection, and generation directly into your own applications.

Introduction

The JourAI API is a REST-based interface for interacting with our newsroom engine. It provides high-performance access to articles, event clusters (topics), and data analytics.

Base URL

All API requests should be made to the following base URL:

https://api.jourai.app

Authentication

Authentication is handled via unique API keys. Each organization is provided with a key that must be included in the header of every request.

Header Required

X-API-Key: your-api-key-here

Unauthorized requests will receive a 401 Unauthorized status. Keys can also be restricted to specific domains for enhanced security.

API Endpoints

GET /api/external/articles

Retrieves published articles for an organization.

Parameters

Name	Type	Req.	Description
`limit`	number	-	Max articles to return (default: 10, max: 100)
`offset`	number	-	Number of articles to skip
`category`	string	-	Filter by category (e.g. "Business")
`language`	string	-	Filter by language code (e.g., "en", "es")
`topics`	string	-	CSV list of topic names
`search`	string	-	Search keywords
`sortBy`	string	-	"createdAt", "publishedAt", "title"

Sample Response

{
  "success": true,
  "data": {
    "articles": [
      {
        "id": 123,
        "title": "Article Title",
        "content": "Full article content...",
        "summary": "Brief article summary...",
        "category": "World",
        "topics": ["Politics"],
        "imageUrl": "https://example.com/image.jpg",
        "publishedAt": "2025-04-22T15:00:00Z",
        "language": "en"
      }
    ],
    "pagination": { "total": 245, "hasMore": true }
  }
}

GET /api/external/topics

Retrieves available topics for an organization.

Name	Type	Description
`limit`	number	Max topics to return (default: 50)
`active`	boolean	Filter by active status (default: true)

GET /api/external/articles/:id

Retrieves a specific article by ID.

Requires an id path parameter.

GET /api/external/categories

Retrieves available article categories.

GET /api/external/statistics

Retrieves article publishing statistics.

Analysis period options: "day", "week", "month", "year".

Rate Limiting

To ensure system stability, the following limits are enforced:

100 requests per minute per API key
5,000 requests per day per API key

Error Handling

We use standard HTTP response codes to indicate request success or failure.

200 OK: Success
400 Bad Request: Invalid parameters
401 Unauthorized: Missing/invalid API key
429 Too Many Requests: Rate limit exceeded

Error Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Implementation Examples

JavaScript

async function fetchArticles(apiKey) {
  const response = await fetch('https://api.jourai.app/api/external/articles', {
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }
  });
  return await response.json();
}

Python

import requests

def fetch_articles(api_key):
    headers = { 'X-API-Key': api_key }
    response = requests.get('https://api.jourai.app/api/external/articles', headers=headers)
    return response.json()