Skip to content

Consuming Alfred v2

🧠 Consuming Alfred v2

Leveraging the various Reflexivity assistants from v1, Alfred v2 is supercharged with reasoning capabilities that enable quantitative analysis far beyond standard assistant functionality. This guide will help you integrate Alfred, our autonomous financial analyst, into your systems. It provides a contained set of APIs to interact with Reflexivity capabilities, with an implementation that varies drastically in comparison to Alfred v1

image of alfred v2 architecture

🔄 Workflow

The interaction with Alfred v2 follows a simple flow: 1. Send your question as a request to the Questions API 2. You will receive a notification on the Notifications API when your question has an update. This notification will include a conversation id 3. Send the conversation id as a request to the Conversations API 4. Response is rendered

NOTE: Steps 2, 3, and 4 are repeated until question is fully answered

📝 Messages

Messages are returned in markdown format with special component links embedded within the markdown. This enables rendering components that cannot be described by markdown alone, such as complex visualizations.

A component link is just like a normal markdown link with a predefined enum in the title section and a UUID within the link section, which is used to get data that the component needs to render.

Example

[chart](656ac7c9720a4d0ca2c8431e8a63fcb7, "line-chart")

Supported Enums

enum component
table table
bar-char bar chart
horizontal-bar-chart horizontal-bar-chart
line-chart advanced line chart
apache-area-time area time
apache-axis-bubble axis bubble
apache-bar-100 bar 100
apache-bar bar chart v2
apache-bar-negative bar chart with negatives
apache-box-whisker boc whisker
apache-bubble bubble
apache-bubble-time bubble time
apache-bump bump chart
apache-candle candle
apache-candle-bar candle bar
apache-confidence confidence
apache-donut donut
apache-donut-time donut time
apache-force-graph force graph
apache-gradient-square gradient square
apache-grouped-bars grouped bars
apache-heatmap heatmap
apache-heatmap-calendar heatmap calendar
apache-line basic line chart
apache-line-and-bar line and bar chart
apache-line-race line chart race version
apache-sankey sankey
apache-sankey-vertical sankey vertical
apache-scatter scatter
apache-stacked-area stacked area
apache-stacked-bar-horizontal tacked bar horizontal
apache-technicals-chart technicals chart
apache-us-map US map visualisation
apache-waterfall waterfall

🛠️ API Reference

Question API

Post a user Question. You may include an optional conversationID, if you would like to continue a previous conversation.

Method: POST

URL: https://api.reflexivity.com/conversation/v1/><Optional<conversationID>

Request Schema:

{
  message: string; // users question
}

Response Schema:

{
  message_id: string;
}

Conversations API

Retrieve all of user's conversations.

Method: GET

URL: https://api.reflexivity.com/conversation/v1

Response Schema:

{
  conversations: Array<{
    name: string;
    date: string;
    id: string;
    summary: string;
    favourite: boolean;
  }>;
}

Messages API

Get a conversation's messages by messageID.

Method: GET

URL: https://api.reflexivity.com/conversation/v1/<conversationID>/messages/<messageID>

Response Schema:

{
    message_id: string;
    conversation_id: string;
    question: string;
    status: "error" | "success"| "pending"| "processing";
    steps: Array<{
            title: "$ACTION_RESOLVER" | "$ACTION_PLANNER" | "$ACTION_TIMESERIES_DATA_GETTER" |" $ACTION_FINANCIAL_STATEMENTS_DATA_GETTER" |"$ACTION_PYTHON_CODE_GENERATOR" | "$ACTION_COMMENTATOR" | "$ACTION_VISUAL_SELECTOR",
            content?: string,  // markdown string
            status: "error"| "success"| "pending"| "processing",
            id?: string,
        }>;
    response?: {
        content?: string, // markdown string
        status: "error"| "success"| "pending"| "processing",
    },
}

Steps description

title Key action description
$ACTION_RESOLVER Resolving entities
$ACTION_PLANNER Evaluating steps to answer query
$ACTION_TIMESERIES_DATA_GETTER Fetching time series data
$ACTION_FINANCIAL_STATEMENTS_DATA_GETTER Gathering financial statements
$ACTION_PYTHON_CODE_GENERATOR Generating code
$ACTION_COMMENTATOR Summarizing key findings
$ACTION_VISUAL_SELECTOR Identifying relevant visualizations"

Steps API

$ACTION_TIMESERIES_DATA_GETTER and ACTION_RESOLVER have custom components which can be rendered. We use this endpoint to get the data required to render the necessary components

Get steps component schema

Method: GET

URL: https://api.reflexivity.com/conversation/v1/><conversationID>/messages/<messageID>/steps/<stepId>

Response Schema for ACTION_TIMESERIES_DATA_GETTER:

{
  error: boolean | null;
  is_success: boolean;
  data_descriptions: Array<{
    display: Array<string>; // markdown string
  }>;
}

Response Schema for ACTION_RESOLVER:

{
  error: boolean | null;
  is_success: boolean;
  resolved: Array<{
    entity: string;
  }>;
}

Notifications API

This is a websocket API which broadcasts messages as below.

URL: wss://ws.reflexivity.com/v2/notifier

Message Response Schema:

{
  event: {
    type: "alfred";
  }
  metadata: {
    conversation_id: string;
    message_id: string;
  }
}

Component API

This API is used to get data for visualizations that are embedded in markdown messages. Responses vary depending on the component ID it is called with.

Method: GET

URL: https://api.reflexivity.com/reasoner-data/v1/<componentID>

Response Schema Table:

type TableData = { value: string; tooltip?: string; logo?: string };
type TableRow<T extends string> = Record<T, TableData>;
type ColumnsType = "text" | "directional" | "number";
type TableColumns<T extends string> = {
  type: ColumnsType;
  sticky?: boolean;
  tooltip?: string;
  id: T;
  title: string;
};
export type TableV2Payload<T extends string> = {
  data: TableRow<T>[];
  stickyHeader?: boolean;
  columnsMeta: TableColumns<T>[];
  pagination?: {
    itemsPerPage?: number;
    strategy?: "scroll" | "buttons";
  };
};

You can view the full list of schemas on Reflexivity's design system.

Update Conversation API

This API currently supports updating of names and favourite status.

Method: PUT

URL: https://api.reflexivity.com/conversation/v1/<conversationID>

Update favourites status request schema:

{
  favourite: boolean;
}

Update name request schema:

{
  name: string;
}

Delete Conversation API

This API allows you to delete a conversation by ID.

Method: Delete

URL: https://api.reflexivity.com/conversation/v1/<conversationID>

Search Conversation

This API allows you to search for messages within a conversation.

Method: Delete

URL: https://api.reflexivity.com/conversation/v1/search?q=&page=0

Response schema:

results: Array<{
  conversation: string;
  conversation_id: string;
  message_id: string;
  summary: string;
  updated_at: string;
}>;

🤝 Need Help?

If you need assistance with the Alfred v2 API or have questions about Reflexivity's platform:

© 2025 Reflexivity