Finlight.me API

https://docs.finlight.me/v2/
Admin
The Finlight.me API is a real-time financial news API that provides market-relevant news articles...
Tokens:29,403
Snippets:258
Trust Score:7.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get All Sources Response Example

Source: https://docs.finlight.me/v2/rest-endpoints

This is an example of the JSON response when requesting all supported article sources. It includes the domain and default status for each source.

```json
[
  {
    "domain": "www.yahoo.com",
    "isDefaultSource": true
  },
  {
    "domain": "seekingalpha.com",
    "isDefaultSource": true
  },
  // ...
]
```

--------------------------------

### Install Node.js Client Library

Source: https://docs.finlight.me/v2

Install the Finlight client library for Node.js using npm. This is the first step before making API calls with the JavaScript client.

```bash
# Install the Node.js client library via npm
npm install finlight-client

```

--------------------------------

### MCP Initialize Request

Source: https://docs.finlight.me/v2/ai-assistants/developers

Example of a client request to initialize an MCP session.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

```

--------------------------------

### MCP Initialize Response

Source: https://docs.finlight.me/v2/ai-assistants/developers

Example of a server response confirming MCP initialization.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "finlight-news-api",
      "version": "1.0.0"
    }
  },
  "id": 1
}

```

--------------------------------

### Search Articles Response Example

Source: https://docs.finlight.me/v2/ai-assistants/developers

Example response structure for the search_articles tool, showing article content, total results, and pagination details.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"articles\":[{\"title\":\"Apple Reports Record Q1...\",\"summary\":\"...\",\"link\":\"https://...\",\"publishDate\":\"2024-02-01T16:30:00Z\",\"source\":\"www.reuters.com\",\"sentiment\":\"positive\",\"sentimentConfidence\":0.92}],\"totalResults\":847,\"page\":1,\"pageSize\":20}"
    }]
  },
  "id": 1
}

```

--------------------------------

### Query Syntax Examples

Source: https://docs.finlight.me/v2/webhooks/enriched

Demonstrates basic query syntax for filtering, including simple phrases, boolean groups, and exclusions.

```text
"Apple earnings"                           simple phrase
(Apple OR iPhone) AND (earnings OR revenue)  boolean groups
Tesla NOT recall                           exclusion

```

--------------------------------

### Example X-Finlight-Key Headers Sent

Source: https://docs.finlight.me/v2/webhooks/authentication

Shows the headers included in a webhook request when using the X-Finlight-Key authentication method.

```http
X-Finlight-Key: your-api-key-value
X-Webhook-Signature: sha256=signature
X-Webhook-Timestamp: 2024-01-15T10:30:00.000Z
```

--------------------------------

### ChatGPT Action Authentication Setup

Source: https://docs.finlight.me/v2/ai-assistants

Configure these URLs for OAuth authentication when setting up a Custom GPT action for finlight.

```yaml
Authentication Type : OAuth
Authorization URL : https://mcp.finlight.me/authorize
Token URL : https://mcp.finlight.me/token
```

--------------------------------

### Server 'sendArticle' Response Example

Source: https://docs.finlight.me/v2/browser-websocket

This JSON object is an example of a 'sendArticle' message from the server, containing details of a new article that matches the client's subscription.

```json
{
  "action": "sendArticle",
  "data": {
    "link": "https://www.reuters.com/technology/nvidia-2026-02-17",
    "source": "www.reuters.com",
    "title": "Nvidia Reports Record Revenue",
    "summary": "Nvidia announced record quarterly revenue...",
    "publishDate": "2026-02-17T10:30:00Z",
    "language": "en",
    "sentiment": "positive",
    "confidence": 0.92,
    "countries": ["US"],
    "categories": ["markets", "technology"],
    "companies": [
      {
        "name": "NVIDIA Corporation",
        "ticker": "NVDA",
        "country": "US"
      }
    ]
  }
}
```

--------------------------------

### Example API Response for Article by Link

Source: https://docs.finlight.me/v2/rest-endpoints

This is an example of the JSON response when successfully fetching an article by its link. It includes article metadata, sentiment analysis, and optionally content and company entities.

```json
{
  "status": "ok",
  "article": {
      "link": "https://www.somepage.com/technology/example-article",
      "source": "www.reuters.com",
      "title": "Nvidia Announces New GPU Architecture",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "createdAt": "2023-10-01T12:35:10Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": 0.95,
      "content": "Full article content here...",
      "images": [
                  "https://www.example.com/image1.jpg"
                ],
      "countries": ["US"],
      "categories": ["technology"],
      "companies": [
                {
                    "companyId": 4157,
                    "confidence": "0.97",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Semiconductors",
                    "name": "NVIDIA Corporation",
                    "sector": "Technology",
                    "ticker": "NVDA",
                    "isin": "US67066G1040",
                    "openfigi": "BBG000BBJQV0"
                }
              ]
  }
}
```

--------------------------------

### Get All Sources (cURL)

Source: https://docs.finlight.me/v2/rest-endpoints

Use this cURL command to retrieve a list of all supported article sources. Replace 'YOUR_API_KEY' with your actual API key.

```bash
curl -X GET 'https://api.finlight.me/v2/sources' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

--------------------------------

### Example Basic Authentication Headers Sent

Source: https://docs.finlight.me/v2/webhooks/authentication

Shows the headers included in a webhook request when using Basic Authentication.

```http
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
X-Webhook-Signature: sha256=signature
X-Webhook-Timestamp: 2024-01-15T10:30:00.000Z
```

--------------------------------

### Webhook Retry Logic Example Scenarios

Source: https://docs.finlight.me/v2/webhooks/good-to-know

Illustrates scenarios of the failure counter resetting upon success and the progression towards auto-disable after consecutive failures.

```text
Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)
```

```text
Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled
```

--------------------------------

### Webhook Quota Usage Example

Source: https://docs.finlight.me/v2/webhooks/good-to-know

Demonstrates how webhook delivery attempts, including retries and failures, impact quota usage.

```text
1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage
```

--------------------------------

### Enriched Webhook Response Example

Source: https://docs.finlight.me/v2/webhooks/enriched

This is a sample payload for an enriched webhook, containing details of a newly published article.

```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs",
  "summary": "A brief summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "language": "en",
  "sentiment": "positive",
  "confidence": 0.95,
  "images": [
    "https://www.example.com/image1.jpg",
    "https://www.example.com/image2.jpg"
  ],
  "countries": ["US"],
  "categories": ["markets", "health"],
  "companies": [
    {
      "companyId": 41494,
      "confidence": "0.9335401058197021",
      "country": "US",
      "exchange": "XNAS",
      "industry": "Biotechnology: Pharmaceutical Preparations",
      "name": "Summit Therapeutics Inc. Common Stock",
      "sector": "Health Care",
      "ticker": "SMMT",
      "isin": "US86627T1088",
      "openfigi": "BBG01PH11VP5",
      "primaryListing": {
        "ticker": "SMMT",
        "exchangeCode": "XNAS",
        "exchangeCountry": "US"
      },
      "isins": ["US86627T1088", "US86627T2088"],
      "otherListings": [
        {
          "ticker": "SMMT.L",
          "exchangeCode": "XLON",
          "exchangeCountry": "GB"
        }
      ]
    }
  ]
}
```

--------------------------------

### Filter by Source and Exclude Keyword

Source: https://docs.finlight.me/v2/webhooks/raw

Retrieve articles from a specific source domain while excluding a particular keyword. This example gets articles from www.reuters.com, excluding those mentioning 'crypto'.

```text
query=source:www.reuters.com -crypto
```

--------------------------------

### Raw WebSocket Article Response Example

Source: https://docs.finlight.me/v2/raw-websocket-subscribe

Illustrates the structure of a standard article object received via the Raw WebSocket API.

```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs",
  "summary": "A brief summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "language": "en",
  "images": [
              "https://www.example.com/image1.jpg",
              "https://www.example.com/image2.jpg"
            ],
  "countries": ["US"],
  "categories": ["markets"]
}

```

--------------------------------

### Get all sources

Source: https://docs.finlight.me/v2/rest-endpoints

Retrieve a list of all currently supported article sources. The sources are scraped on a best-effort basis and may change in the future.

```APIDOC
## GET /v2/sources

### Description
Retrieve a list of all currently supported article sources. The sources are scraped on a best-effort basis and may change in the future.

### Method
GET

### Endpoint
/v2/sources

### Request Example
```curl
curl -X GET 'https://api.finlight.me/v2/sources' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

### Response
#### Success Response (200)
A JSON array of source objects.

- **domain** (string) - Domain of the source website.
- **isDefaultSource** (boolean) - Indicates if this source is a default source for the API.

#### Response Example
```json
[
  {
    "domain": "www.yahoo.com",
    "isDefaultSource": true
  },
  {
    "domain": "seekingalpha.com",
    "isDefaultSource": true
  }
]
```
```

--------------------------------

### Fetch Articles with Finlight API

Source: https://docs.finlight.me/v2

Make a GET request to the Articles endpoint to search for financial news. Replace 'YOUR_API_KEY' with your actual API key. This snippet demonstrates basic article fetching with a query and language filter.

```typescript
import { FinlightApi } from "finlight-client";

const api = new FinlightApi({ apiKey: 'YOUR_API_KEY' }) // Replace with your API key

api.articles
  .fetchArticles({
    query: "Nvidia",
    language: "en"
  })
  .then((articles) => console.log(articles));
  .catch((error) => console.error(error))

```

--------------------------------

### Filter by Summary and Title

Source: https://docs.finlight.me/v2/webhooks/raw

Combine summary and title filters to narrow down results. This example retrieves articles mentioning 'earnings' in the summary and 'Tesla' in the title.

```text
query=summary:earnings +title:Tesla
```

--------------------------------

### Server 'admit' Response Example

Source: https://docs.finlight.me/v2/browser-websocket

This JSON object represents the server's response after a successful WebSocket handshake. It includes a lease ID, server timestamp, and the client's nonce.

```json
{
  "action": "admit",
  "leaseId": "a1b2c3d4-e5f6-4789-abcd-ef0123456789",
  "serverNow": 1708185600000,
  "clientNonce": "your-uuid-here"
}
```

--------------------------------

### Enriched Webhook Response for Updated Articles

Source: https://docs.finlight.me/v2/webhooks/enriched

This example shows the payload structure when an article is updated and `includeUpdates` is set to true. It includes `revisedDate` and `isUpdate` fields.

```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs — Updated",
  "summary": "An updated summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "revisedDate": "2023-10-02T08:00:00Z",
  "isUpdate": true,
  "language": "en",
  "sentiment": "positive",
  "confidence": 0.95,
  "images": [
    "https://www.example.com/image1.jpg"
  ],
  "countries": ["US"],
  "categories": ["markets"],
  "companies": []
}
```

--------------------------------

### Article Response Structure

Source: https://docs.finlight.me/v2/rest-endpoints

This is an example of the JSON response structure when fetching articles. It includes metadata like page number and size, along with a list of articles, each containing details such as link, source, title, summary, and more.

```json
{
  "status": "ok",
  "page": 1,
  "pageSize": 20,
  "articles": [
    {
      "link": "https://www.example.com/article1",
      "source": "www.example.com",
      "title": "Stock Market Hits New Highs",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": 0.95,
      "images": [
                  "https://www.example.com/image1.jpg",
                  "https://www.example.com/image2.jpg"
                ],
      "countries": ["US"],
      "categories": ["markets", "technology"],
      "companies": [
                {
                    "companyId": 41494,
                    "confidence": "0.9335401058197021",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Biotechnology: Pharmaceutical Preparations",
                    "name": "Summit Therapeutics Inc. Common Stock",
                    "sector": "Health Care",
                    "ticker": "SMMT",
                    "isin": "US86627T1088",
                    "openfigi": "BBG01PH11VP5",
                    "primaryListing": {
                        "ticker": "SMMT",
                        "exchangeCode": "XNAS",
                        "exchangeCountry": "US"
                    },
                    "isins": ["US86627T1088", "US86627T2088"],
                    "otherListings": [
                        {
                            "ticker": "SMMT.L",
                            "exchangeCode": "XLON",
                            "exchangeCountry": "GB"
                        }
                    ]
                },
                ...
              ]
    },
    // ...
  ]
}
```

--------------------------------

### Connect and List Tools with TypeScript SDK

Source: https://docs.finlight.me/v2/ai-assistants/developers

Initialize the MCP client with a transport layer and connect to the server. Use the client to list available tools.

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.finlight.me"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.FINLIGHT_API_KEY}`,
      },
    },
  }
);

const client = new Client({
  name: "my-app",
  version: "1.0.0",
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools);
```

--------------------------------

### Connect to WebSocket API (Basic)

Source: https://docs.finlight.me/v2/websocket-quickstart

Connect to the Finlight.me WebSocket API using the Node.js client. This snippet shows how to initialize the client with an API key and establish a connection to receive articles matching a query.

```typescript
import { FinlightApi } from 'finlight-client'

const client = new FinlightApi({
  apiKey: 'YOUR_API_KEY',
})

client.websocket.connect(
  { query: 'nvidia', language: 'en' },
  (article) => {
    console.log('New article received:', article)
  },
)

```

--------------------------------

### OAuth Flow Overview

Source: https://docs.finlight.me/v2/ai-assistants/developers

Steps involved in the OAuth 2.0 flow with PKCE for client authentication.

```text
1. Client discovers OAuth endpoints via .well-known
2. Client optionally registers via /register
3. Client redirects user to /authorize with PKCE challenge
4. User enters API key and submits
5. Server redirects back with authorization code
6. Client exchanges code + verifier for access token
7. Client uses access token as Bearer token for API calls

```

--------------------------------

### finlight Server URL for Claude Desktop

Source: https://docs.finlight.me/v2/ai-assistants

Use this URL when adding finlight as an MCP server in Claude Desktop settings.

```text
https://mcp.finlight.me
```

--------------------------------

### List Available Tools with cURL

Source: https://docs.finlight.me/v2/ai-assistants/developers

Use cURL to send a POST request to the MCP server to list available tools. Ensure you include the correct Content-Type and Authorization headers.

```shell
curl -X POST https://mcp.finlight.me \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ \
    "jsonrpc": "2.0", \
    "id": 1, \
    "method": "tools/list" \
  }'
```

--------------------------------

### Enable Takeover for Connection Limits (Python)

Source: https://docs.finlight.me/v2/websocket-subscribe

Initializes the Finlight API client with the `takeover` option enabled for WebSocket connections. This automatically closes the oldest connection when the limit is reached.

```python
# Python example with takeover enabled
from finlight_client import FinlightApi, ApiConfig, WebSocketOptions

client = FinlightApi(
    config=ApiConfig(api_key="YOUR_API_KEY"),
    websocket_options=WebSocketOptions(takeover=True)
)


```

--------------------------------

### List Tools and Search Articles with Python

Source: https://docs.finlight.me/v2/ai-assistants/developers

Use the `mcp_request` function to list available tools and search for articles, printing the JSON responses.

```python
# List available tools
tools = mcp_request("tools/list")
print("Available tools:", json.dumps(tools, indent=2))

# Search articles
articles = mcp_request("tools/call", {
    "name": "search_articles",
    "arguments": {
        "query": "Tesla Model 3",
        "tickers": ["TSLA"],
        "from": "2024-01-01",
        "pageSize": 10,
    },
})
print("Articles:", json.dumps(articles, indent=2))
```

--------------------------------

### API Error Response Structure

Source: https://docs.finlight.me/v2/ai-assistants/developers

This is an example of an error response structure for failed tool calls. It indicates an error occurred and provides details in the 'content' field.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Error: Invalid API key"
      }
    ]
  },
  "id": 1
}

```

--------------------------------

### Required and Excluded Fields

Source: https://docs.finlight.me/v2/advanced-query-building

Use '+' for required fields and '-' for excluded fields to refine search results. This example targets Tesla news from specific sources, excluding crypto.

```text
query=+ticker:TSLA -crypto AND (+source:www.bloomberg.com OR +source:www.reuters.com)
```

--------------------------------

### Enable Takeover for Connection Limits (TypeScript)

Source: https://docs.finlight.me/v2/websocket-subscribe

Initializes the Finlight API client with the `takeover` option enabled for WebSocket connections. This automatically closes the oldest connection when the limit is reached.

```typescript
// TypeScript example with takeover enabled
const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
  },
  {
    takeover: true, // Automatically close oldest connection when limit is reached
  },
)


```

--------------------------------

### OAuth Flow

Source: https://docs.finlight.me/v2/ai-assistants/developers

The server implements OAuth 2.0 with PKCE for clients that support OAuth, enabling secure authorization.

```APIDOC
## OAuth Flow

For clients that support OAuth (like Claude Desktop), the server implements OAuth 2.0 with PKCE.

### Endpoints

#### `/.well-known/oauth-protected-resource`

##### Description
Protected resource metadata.

##### Method
GET

#### `/.well-known/oauth-authorization-server`

##### Description
Authorization server metadata.

##### Method
GET

#### `/register`

##### Description
Dynamic client registration.

##### Method
POST

#### `/authorize`

##### Description
Authorization page.

##### Method
GET

#### `/authorize/submit`

##### Description
Process authorization.

##### Method
POST

#### `/token`

##### Description
Exchange code for token.

##### Method
POST

### Flow Overview

```
1. Client discovers OAuth endpoints via .well-known
2. Client optionally registers via /register
3. Client redirects user to /authorize with PKCE challenge
4. User enters API key and submits
5. Server redirects back with authorization code
6. Client exchanges code + verifier for access token
7. Client uses access token as Bearer token for API calls
```

### Security Features

*   **PKCE Required** - Prevents authorization code interception
*   **Self-Encrypted Codes** - AES-256-GCM encrypted, stateless
*   **Short-Lived Codes** - 120 second expiration
*   **Redirect URI Validation** - Codes bound to original URI
```

--------------------------------

### WebSocket Endpoint

Source: https://docs.finlight.me/v2/websocket-basics

The base URL for establishing a WebSocket connection to the Finlight.me server.

```text
wss://wss.finlight.me
```

--------------------------------

### Connect to WebSocket API with Takeover Option

Source: https://docs.finlight.me/v2/websocket-quickstart

Establish a WebSocket connection with the 'takeover' option enabled. This allows the new connection to automatically close the oldest existing connection if the connection limit is reached.

```typescript
import { FinlightApi } from 'finlight-client'

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
  },
  {
    // WebSocket-specific options
    takeover: true, // Automatically close oldest connection when limit is reached (default: false)
  },
)

client.websocket.connect(
  { query: 'nvidia', language: 'en' },
  (article) => {
    console.log('New article received:', article)
  },
)

```

--------------------------------

### Fetch Articles with Query and Countries

Source: https://docs.finlight.me/v2/rest-endpoints

Use this cURL command to fetch articles. It demonstrates filtering by a specific query and a list of countries. Replace 'YOUR_API_KEY' with your actual API key.

```curl
curl -X POST 'https://api.finlight.me/v2/articles' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{ "query": "Nvidia", "countries": ["US", "GB"] }'
```

--------------------------------

### List Available Tools

Source: https://docs.finlight.me/v2/ai-assistants/developers

Retrieves a list of all available tools that can be called via the MCP server. This is useful for discovering the capabilities of the API.

```APIDOC
## POST /jsonrpc

### Description
Lists all available tools that can be invoked through the MCP server.

### Method
POST

### Endpoint
https://mcp.finlight.me

### Headers
- **Content-Type**: application/json
- **Authorization**: Bearer YOUR_API_KEY

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains a list of available tools.
- **id** (integer) - The ID of the request.

### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_articles",
        "description": "Search for financial articles."
      }
    ]
  }
}
```
```

--------------------------------

### WebSocket Connection Parameters

Source: https://docs.finlight.me/v2/browser-websocket

Parameters used when establishing a WebSocket connection to the Finlight API. These are passed as query parameters in the WebSocket URL.

```APIDOC
## WebSocket Connection

### Description
Establishes a WebSocket connection to the Finlight API. Query parameters are used for authentication and configuration.

### Query Parameters

- **apiKey** (string) - Required - Your Finlight API key. Used for authentication since browser WebSocket cannot set custom headers.
- **takeover** (string) - Optional - Set to `"true"` to automatically replace the oldest connection when your concurrent connection limit is reached.
- **clientVersion** (string) - Optional - Optional identifier for your client application. E.g. `"my-dashboard/1.0"`
```

--------------------------------

### Fetch Article by Link (cURL)

Source: https://docs.finlight.me/v2/rest-endpoints

Use this cURL command to retrieve a single article by its URL. You can optionally include the full article content and company entities by setting the respective query parameters to true. Remember to replace YOUR_API_KEY with your actual API key.

```curl
curl -X GET 'https://api.finlight.me/v2/articles/by-link?link=https%3A%2F%2Fwww.somepage.com%2Ftechnology%2Fexample-article&includeContent=true&includeEntities=true' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

--------------------------------

### Combining Fields and Wildcards

Source: https://docs.finlight.me/v2/advanced-query-building

Utilize wildcards (*) with fields like 'source', 'ticker', and 'exchange' for broad matching, and combine with boolean logic.

```text
query=ticker:* AND (country:US OR country:GB) -crypto
query=source:* exchange:XNAS
```

--------------------------------

### Fetch Articles via WebSocket

Source: https://docs.finlight.me/v2/raw-websocket-subscribe

Connect to the Raw WebSocket endpoint to receive real-time articles. You can filter articles by providing a search query, specific sources, and language. The `includeUpdates` parameter can be set to true to also receive updated articles.

```APIDOC
## Fetch articles

After connecting, you will only receive **newly published articles** that match your criteria. No initial/historical article is sent on connection.

When subscribing, you can specify the following parameters to filter the articles you receive:

* **`query`** (string) - Search query to find relevant articles. Supports field-level filtering for `source`, `title`, and `summary` fields.
* **`sources`** (string[]) - Filter by single or multiple sources. E.g. `["www.reuters.com", "www.cnbc.com"]`.
* **`excludeSources`** (string[]) - Exclude single or multiple sources. E.g. `["www.reuters.com", "www.cnbc.com"]`.
* **`language`** (string) - Filter by language. Language code in ISO 639-1.
* **`includeUpdates`** (boolean) - When enabled, updated articles are re-delivered with `isUpdate=true` and a `revisedDate` timestamp.

### Request Example
```typescript
import { FinlightApi } from 'finlight-client'

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY', // Replace with your API key
  },
  {
    takeover: true, // WebSocket options
  },
)

client.rawWebsocket.connect(
  {
    query: 'Nvidia',
    language: 'en',
    sources: ['www.reuters.com', 'www.cnbc.com'],
  },
  (article) => {
    console.log('New article received:', article)
  },
)
```

### Response Example
```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs",
  "summary": "A brief summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "language": "en",
  "images": [
              "https://www.example.com/image1.jpg",
              "https://www.example.com/image2.jpg"
            ],
  "countries": ["US"],
  "categories": ["markets"]
}
```

### Response Example (includeUpdates: true)
```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs — Updated",
  "summary": "An updated summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "revisedDate": "2023-10-02T08:00:00Z",
  "isUpdate": true,
  "language": "en",
  "images": [
    "https://www.example.com/image1.jpg"
  ],
  "countries": ["US"],
  "categories": ["markets"]
}
```

### Query Field-Level Filtering
The Raw WebSocket supports field-level filtering within the `query` parameter for the following fields:

* **`source`** - Filter by article source
* **`title`** - Filter by article title content
* **`summary`** - Filter by article summary content

**Examples:**
```
query=title:Nvidia
```
Returns articles where the title contains "Nvidia".

```
query=summary:earnings +title:Tesla
```
Returns articles where the summary mentions "earnings" and the title contains "Tesla".

```
query=source:www.reuters.com -crypto
```
Returns articles from Reuters, excluding those mentioning "crypto".

### Connection Behavior
* **Authentication**: Uses the same `x-api-key` header as the Enhanced WebSocket.
* **Ping/Pong**: Send periodic `ping` messages to maintain the connection.
* **Connection Duration**: Subject to the same 2-hour connection limit. Implement reconnect logic accordingly.
* **No Initial Data**: Only newly published articles are delivered after connection.
```

--------------------------------

### Node.js WebSocket Connection with Authentication

Source: https://docs.finlight.me/v2/websocket-basics

Connect to the Finlight.me WebSocket server using Node.js, providing your API key in the connection headers for authentication.

```javascript
const WebSocket = require('ws')

const socket = new WebSocket('wss://wss.finlight.me', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
})

socket.on('open', () => {
  console.log('Connected to Finlight.me WebSocket!')
  // You can now send a subscription request to start receiving articles
})

socket.on('error', (err) => {
  console.error('WebSocket error:', err)
})

```

--------------------------------

### List Available News Sources

Source: https://docs.finlight.me/v2/ai-assistants/developers

Retrieve a list of all available news sources supported by the system. This includes their domain, whether they are default sources, and if full content retrieval is supported.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_sources",
    "arguments": {}
  }
}

```

--------------------------------

### Connect to Raw WebSocket and Subscribe to Articles

Source: https://docs.finlight.me/v2/raw-websocket-subscribe

Connects to the Raw WebSocket API using a provided API key and subscribes to articles matching specific criteria. The callback function processes each received article.

```typescript
import { FinlightApi } from 'finlight-client'

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY', // Replace with your API key
  },
  {
    takeover: true, // WebSocket options
  },
)

client.rawWebsocket.connect(
  {
    query: 'Nvidia',
    language: 'en',
    sources: ['www.reuters.com', 'www.cnbc.com'],
  },
  (article) => {
    console.log('New article received:', article)
  },
)

```

--------------------------------

### Search Articles with TypeScript SDK

Source: https://docs.finlight.me/v2/ai-assistants/developers

Use the MCP client to call the 'search_articles' tool with specified arguments including query, date range, and page size.

```typescript
// Search articles
const result = await client.callTool({
  name: "search_articles",
  arguments: {
    query: "Federal Reserve interest rates",
    from: "2024-01-01",
    pageSize: 5,
  },
});

console.log("Articles:", result);
```

--------------------------------

### Validate X-Finlight-Key Header

Source: https://docs.finlight.me/v2/webhooks/authentication

Implement this on your endpoint to verify the API key sent in the X-Finlight-Key header. Ensure the key matches your expected value.

```javascript
const finlightKey = req.headers['x-finlight-key']
if (finlightKey !== 'your-expected-api-key') {
  return res.status(401).send('Invalid API key')
}
```

--------------------------------

### Subscribe to Articles

Source: https://docs.finlight.me/v2/raw-websocket-subscribe

Connect to the Raw WebSocket endpoint to receive real-time article data. This endpoint delivers core article information without any enrichment or matching, making it a lightweight option for basic data needs.

```APIDOC
## Subscribe to Articles

### Description
Connect to the Raw WebSocket endpoint to receive real-time article data. This endpoint delivers core article information without any enrichment or matching, making it a lightweight option for basic data needs.

### Method
Establish a WebSocket connection.

### Endpoint
`wss://wss.finlight.me/raw`

### Parameters
This endpoint does not accept any parameters.

### Article Model
The Raw WebSocket returns a simplified article model with the following core fields:

- **link** (string) - URL to the full article.
- **source** (string) - Source website (e.g., `www.reuters.com`).
- **title** (string) - Title of the article.
- **summary** (string) - Summary of the article, can be nullable.
- **publishDate** (Date) - Publication date as ISO date.
- **createdAt** (Date) - Internal creation date of the article in the finlight system as ISO date.
- **revisedDate** (Date | null) - Date the article was last revised after initial publication. `null` when the article has never been revised.
- **isUpdate** (boolean) - `true` when this delivery is triggered by a post-publication update to the article.
- **language** (string) - Language code in ISO 639-1 (e.g., `en`, `de`, `fr`).
- **images** (string[]) - Array of image URLs from the article.
- **countries** (string[]) - Array of country codes in ISO 3166-1 alpha-2 format (e.g., `["US", "GB", "DE"]`).
- **categories** (string[]) - Array of article categories (e.g., `markets`, `economy`, `business`).

### Notes
- Unlike the Enhanced WebSocket, the Raw WebSocket does not send the latest matching article on connection or reconnection. You will only receive newly published articles after connecting.
- Articles are delivered without sentiment analysis, company matching, or ticker resolution.
- Simplified parameters: No `tickers`, `countries`, `includeEntities`, or `extended` parameters are accepted.
```

--------------------------------

### Create Raw Webhook

Source: https://docs.finlight.me/v2/webhooks/raw

This endpoint allows you to create a raw webhook. Raw webhooks are configured to deliver only newly published articles that match your specified criteria. Each delivery is a single article payload sent as an HTTP POST request to your endpoint.

```APIDOC
## Create a Raw Webhook

### Description
Creates a raw webhook that delivers newly published articles matching specified criteria. Each delivery is a single article payload sent as an HTTP POST request to your endpoint.

### Method
POST

### Endpoint
`/webhooks/raw`

### Parameters
#### Query Parameters
- **query** (string) - Required - Search query to find relevant articles. Supports field-level filtering for `source`, `title`, and `summary` fields.
- **sources** (string[]) - Optional - Limit delivery to articles from specific sources. E.g. `["www.reuters.com", "www.cnbc.com"]`.
- **excludeSources** (string[]) - Optional - Exclude articles from specific sources. E.g. `["www.example.com"]`.
- **language** (string) - Optional - Filter by article language. Language code in ISO 639-1. Defaults to `en` when not set.
- **includeUpdates** (boolean) - Optional - Re-deliver articles when they are updated after initial publication. Updated payloads include `isUpdate=true` and a `revisedDate` timestamp.

### Response
#### Success Response (200)
- **link** (string) - URL of the article.
- **source** (string) - The source domain of the article.
- **title** (string) - The title of the article.
- **summary** (string) - A brief summary of the article.
- **publishDate** (string) - The publication date of the article (ISO 8601 format).
- **createdAt** (string) - The timestamp when the webhook delivery was created (ISO 8601 format).
- **language** (string) - The language of the article.
- **images** (string[]) - An array of image URLs associated with the article.
- **countries** (string[]) - An array of country codes associated with the article.
- **categories** (string[]) - An array of categories associated with the article.
- **revisedDate** (string) - The timestamp when the article was last revised (ISO 8601 format). Only present if `includeUpdates` is true and the article is an update.
- **isUpdate** (boolean) - Indicates if the payload is an updated version of an article. Only present if `includeUpdates` is true.

### Response Example
```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs",
  "summary": "A brief summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "language": "en",
  "images": [
    "https://www.example.com/image1.jpg",
    "https://www.example.com/image2.jpg"
  ],
  "countries": ["US"],
  "categories": ["markets"]
}
```

### Response Example (includeUpdates: true)
```json
{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs — Updated",
  "summary": "An updated summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "createdAt": "2023-10-01T12:35:10Z",
  "revisedDate": "2023-10-02T08:00:00Z",
  "isUpdate": true,
  "language": "en",
  "images": [
    "https://www.example.com/image1.jpg"
  ],
  "countries": ["US"],
  "categories": ["markets"]
}
```
```

--------------------------------

### Signature Calculation Algorithm

Source: https://docs.finlight.me/v2/webhooks/authentication

Illustrates the HMAC-SHA256 algorithm used by finlight to generate webhook signatures based on the timestamp and payload.

```plaintext
message = timestamp + '.' + JSON.stringify(payload)
signature = HMAC-SHA256(message, webhook_secret)
```

--------------------------------

### Make MCP Requests with Python

Source: https://docs.finlight.me/v2/ai-assistants/developers

Define a helper function to make JSON-RPC requests to the MCP server, handling authentication and request formatting. This function can be used for listing tools and searching articles.

```python
import requests
import json

API_KEY = "your-api-key"
MCP_URL = "https://mcp.finlight.me"

def mcp_request(method: str, params: dict = None):
    response = requests.post(
        MCP_URL,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {API_KEY}",
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": method,
            "params": params or {},
        },
    )
    return response.json()
```

--------------------------------

### Authenticate with API Key

Source: https://docs.finlight.me/v2/ai-assistants/developers

All tool calls require authentication via Bearer token using your finlight API key.

```text
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Wildcard Search for All Sources

Source: https://docs.finlight.me/v2/advanced-query-building

Use a wildcard '*' with the 'source' field to retrieve articles from all available sources.

```text
query=source:*
```

--------------------------------

### Filter Articles by Summary and Title

Source: https://docs.finlight.me/v2/raw-websocket-subscribe

Shows how to combine filters for `summary` and `title` fields within the `query` parameter to refine search results.

```text
query=summary:earnings +title:Tesla

```

--------------------------------

### Subscribe to Articles with Filters (TypeScript)

Source: https://docs.finlight.me/v2/websocket-subscribe

Connects to the WebSocket and subscribes to articles matching the specified query and filters. The callback function processes each received article.

```typescript
import { FinlightApi } from 'finlight-client'

const client = new FinlightApi({
  apiKey: 'YOUR_API_KEY', // Replace with your API key
})

client.websocket.connect(
  {
    query: 'Nvidia',
    language: 'en',
    extended: true,
    countries: ['US', 'GB'],
  },
  (article) => {
    console.log('New article received:', article)
  },
)


```

--------------------------------

### Basic Boolean Operators

Source: https://docs.finlight.me/v2/advanced-query-building

Use AND, OR, and NOT to combine or exclude search terms. Terms are AND-joined by default.

```text
query=stock AND google
query=amazon OR google
query=market AND NOT bitcoin
```
Tokens:
Raw