Skip to content

FTS Generative API

The FTS Generative API is a collection of endpoints that allow you to combine the full power of FTS news search with LLM (Large Language Model) based text generation.

Authentication

The FTS Generative API uses the same authentication methods as the rest of the FTS API. For more information, see the Authentication page.

Overview

At its core, the FTS Generative API provides a layer of abstraction over existing LLM APIs. As such, they are used much the same - you provide a "thread" of messages, choose a model, and the API will generate a response based on the conversation. Responses are streamed as they are generated using Server-Sent Events (SSE), allowing for real-time analysis of the output.

The unique capabilities of the FTS Generative API come from the ability to automatically inject articles into the context of the conversation. Articles can be provided explicitly via unique user messages, or pulled implicitly at the discretion of the model via Retrieval Augmented Generation (RAG).

Schemas

Full details on all referenced schemas can be found in the FTS API docs.

Temporary / Transient Conversation (POST /generative/generate)

This endpoint accepts a conversation thread and generates a response using the specified model. None of the conversation is stored and this endpoint has no access to other conversation history. This is useful for generating responses to a single query without the need to maintain a conversation history, or for cases where the conversation history is managed elsewhere.

When streaming is set to true, the Accept: text/event-stream header should be included in the request to indicate the client is capable of handling SSE.

Inputs

The body of the request must follow the structure of the GenerateBody schema, which includes the following fields:

  • version ('0' | '1') [required]: The version of the output formatting to use. Version 1 is the latest and recommended version. Version 0 is currently used for the FTS Chart Explainer plugin, but is otherwise deprecated and should not be used for new integrations.
  • model (GenerativeModel) [required]: The specific model to use for generation.
  • messages (NewGenerativeMessage[]) [required]: The sequence of messages that form the conversation thread.
  • streaming (boolean) [required]: Indicates whether the response should be streamed in real-time or once when the generation is complete.
  • truncationStrategy (GenerativeTruncationStrategy) [optional]: Strategy to use if the conversation exceeds the maximum token length for the chosen model. It is recommended to always provide this option.
  • useDirectArticleURL (boolean) [optional]: If true, instructs the model to use the direct URLs to the articles in the response. If false, articles will be referenced using URLs to the FTS platform.

Messages

Messages in the conversation thread are defined by the NewGenerativeMessage interface, which is detailed in the schemas documentation.

  • role: Defines the source of the message. Can be either user, tool, or assistant.
  • content: Represents the content of the message. Available options are:
    • TextGenerativeContent: Used to provide simple text input.
    • FTSNewsGenerativeContent: Used to inject an explicit list of articles into the conversation.
    • FTSTemplateGenerativeContent: Used to inject a pre-defined prompt into the conversation.

Each content object may include a metadata object, which defines non-text information used in generation. The following fields are available, but are usually automatically created during generation:

  • tool_calls (GenerativeToolCall[]) [optional]: Created by the assistant to instruct the API to perform tool call(s), and defines the parameters for the API to use when making the tool call.
  • tool_call_id (string) [optional]: Required on any tool message to refer to the tool_calls object in the previous assistant message.

The following fields are available for you to enrich the conversation further:

  • news_context (GenerativeNewsContext) [optional]: An optional object that can be used to enforce search parameters for implicit article retrieval using RAG. The following fields are available:
    • start (number) [optional]: A Unix timestamp representing the start of the search window.
    • end (number) [optional]: A Unix timestamp representing the end of the search window.
    • stages (ChannelStage[]) [optional]: An array of base filters that will be included on each search.
    • sorting (NewsFeedSort) [optional]: The sorting method to use for the articles.
    • useFullText (boolean) [optional]: true to inject full articles in the conversation, or false to only provide truncated versions.

Injecting Articles

Explicit article injection is done using the previously-mentioned FTSNewsGenerativeContent object. The only required field is articleIds, which is an array of FTS article IDs to inject into the conversation. These can be retrieved using the FTS News APIs.

Implicit injection is done using RAG and at the discretion of the model. The model may attempt to retrieve additional articles if the current conversation contains insufficient information to generate an informed response to the most recent prompt. This is likely to occur if no articles are explicitly injected into the conversation, or if the prompt is beyond the scope of the injected articles.

Implicit injection will use the information in the conversation to attempt to build a set of search filters that will be used to retrieve articles. The API will attempt to disambiguate each search filter into an entity within the FTS knowledge-base, and failing that will use the filter as a keyword search. Disambiguation is done using any name, type, symbol, and/or FIGI provided in the conversation. It is recommended to provide as much information as possible to ensure the best results. The EntityGroup schema provides a list of all possible entity types that may be used for disambiguation.

If the conversation mentions multiple filters, the API will attempt to disambiguate each filter individually and then combine them into a single search query using an "AND" operation - for example, asking for news about "Apple" and "earnings" will result in a search for articles that contain tags for both "Apple" and "earnings".

The context used for article retrieval can be controlled by providing parameters in content.metadata.news_context on any message in the conversation. The most recent news_context object in the conversation will be used for any searches. Additionally, the same search parameters from any explicit FTSNewsGenerativeContent object will be used, if provided. Any stages provided via either method will be combined with the disambiguated search filters to form the final search query.

Streaming

EventSource interface

Although the HTML Living Standard specification includes the EventSource interface for handling Server-Sent Events, the FTS Generative APIs use the POST method for generation endpoints, which is not supported by EventSource. Instead, you should use the fetch API or a similar method, and then manually parse the events from each response.

When the streaming field is set to true, the response is streamed as a sequence of Server-Sent Events (SSE). Read more about SSE in the HTML Living Standard.

Each event includes the following fields:

  • event: the type of message being sent
  • data: the payload of the message

The general format of an SSE data packet is:

event: <event-type>\ndata: <data-payload>\n\n

A single newline separates fields in an event, and a double-newline separates different events. Multiple events can be embedded in a single response.

Response (v1) - Streaming

In v1, the response is streamed such that the data field of each event always contains a JSON payload.

Event Types (v1)

  • message: Represents any message from the assistant. The data field contains a JSON payload with the following fields:

    • type (string): The type of content in the message. Can be ai_part, tool_start, or tool_finish.
    • message (NewGenerativeMessage): The content of the message. This will always match the shape of the NewGenerativeMessage schema, but its contents will vary depending on the type field.

    Example:

    event: message
data: { "type": "ai_part", "message": { "role": "assistant", "content": { "type": "text", "text": "The latest trends in renewable energy include..." } } }

  • error: Represents an error message from the API. The data field contains a JSON payload describing the error.

Message Types

  • ai_part: Represents a partial message from the assistant. The contents of message.content.text can be concatenated to any prior ai_part events to form the full response.
  • tool_start: Indicates that the assistant has requested a tool to be invoked, e.g. searching for articles to inject into the conversation. The message.content field describes the tool being invoked and any arguments associated with it.
  • tool_finish: Indicates the completion of a tool operation. The message.content field contains a JSON payload with the results of the tool operation - e.g. a list of article IDs that have been injected into the conversation.

Response (v1) - Non-Streaming

When the streaming field is set to false, the response is returned as a single JSON object with the following fields:

  • messages (GenerativeMessage[]): The sequence of messages that form the conversation thread.

Due to the nature of LLM text-generation, this method is not recommended for real-time applications, as it may take a significant amount of time to generate a response.

Response (v0, deprecated) - Streaming

Deprecated

Although version 0 is currently being used in the FTS Chart Explainer plugin, it is otherwise deprecated and should not be used for new integrations. It has limitations that are addressed in version 1, such as inconsistent output formatting, poor non-streaming support, and requiring the client to switch to JSON response type in case of an error.

Event Types (v0)

  • chat_message: Represents a partial message from the assistant. In this case, the data field contains plain text, which is a portion of the generated response. The data from a chat_message event can be concatenated to any prior chat_message events to form the full response.

    Example:

    event: chat_message
data: The latest trends in renewable energy include...

  • start_tool: Indicates that the assistant has requested a tool to be invoked, e.g. searching for articles to inject into the conversation. The data field describes the tool being invoked and any arguments associated with it.

    Example:

    event: start_tool
data: { "role": "assistant", "content": { "type": "text", "text": "", "metadata": { "tool_calls": [{ "id": "tool_call_12345", "name": "search_articles", "args": {}, "type": "tool_call" }] } } }

  • finish_tool: Indicates the completion of a tool operation. The data field contains a JSON payload with the results of the tool operation - e.g. a list of article IDs that have been injected into the conversation.

    Example:

    event: finish_tool
data: { "role": "tool", "content": { "type": "fts_news", "articleIds": [12345, 67890], "metadata": { "tool_call_id": "tool_call_12345" } } }

Errors

Errors are returned as a standard JSON object with an error field containing the error message. Clients will have to switch to accepting JSON response type if an error occurs.

Examples

Injecting articles into the conversation explicitly

{
  "version": "1", 
  "model": "gpt4o",
  "streaming": true,
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "fts_news",
        "articleIds": [12345, 67890, 454545, 54321, 22222],
        "useFullText": true,
        "count": 5,
        "sorting": "trending",
        "stages": []
      }
    },
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Provide a summary of the key points from the provided articles."
      }
    }
  ]
}

Searching for news about a specific topic (injecting articles implicitly)

{
  "version": "1",
  "model": "gpt4o",
  "streaming": true,
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "What are the latest trends for politics in Japan?"
      }
    }
  ]
}

Providing context for implicit article retrieval

{
  "version": "1",
  "model": "gpt4o",
  "streaming": true,
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Why is Hyundai in the news today?",
        "metadata": {
          "news_context": {
            "useFullText": true,
            "start": 1653192000000,
            "end":  1653278399999,
            "sorting": "trending",
            "count": 10,
            "stages": [
              {
                "not": false,
                "entities": [
                  {
                    "type": "entity",
                    "value": 3
                  }
                ]
              },
              {
                "not": false,
                "entities": [
                  {
                    "type": "entity",
                    "value": 36501
                  }
                ]
              }
            ]
          }
        }
      }
    }
  ]
}
Last update: January 7, 2025
Back to top