Consuming Alfred v1

🧠 Consuming Alfred V1¶

This guide will help you integrate Alfred, our autonomous financial analyst, into your systems. The Alfred v1 API provides a streaming interface to interact with various Reflexivity assistants, each bringing unique capabilities to your financial analysis workflow.

an image of the alfred v1 architecture

🔐 Authentication¶

To start using the Alfred API you will need to obtain an Authentication token from the Authentication service and attach it as a Authorization header with all your requests:

Authorization: Bearer <token>

📡 Request¶

HTTP Method¶

POST

Headers¶

Header	Type	Required	Description
`Authorization`	`string`	Yes	Bearer token authentication
`Content-Type`	`string`	Yes	Must be `application/json`

Request Body¶

{
  question: string;         // The user's query
  session_id: string;       // Unique session identifier (uuid format)
  target?: string;          // Optional: Specific assistant to target
  ancillary?: {             // Optional: Additional context
    documents?: string[];   // Document IDs for context
  };
}

Target Reflexivity Assistant Options¶

"all" (default) - Routes to all assistants
"document-assistant" - Document analysis
"scenario-assistant" - Scenario analysis
"chart-assistant" - Chart generation
"fallback-assistant" - General responses

📊 Response Stream¶

Stream Format¶

The response is streamed as a series of JSON objects, each representing a response from specific service.

{
  source: string;                   // Source of the response
  data: {                           // Response data with confidence scoring
    confidence: number;             // Confidence score (0-1) for the assistant's response
    scores: Record<string, number>; // Detailed scoring breakdown
    [key: string]: any;             // Additional service-specific data
  };
  request_id: string;              // Request identifier this will be what was sent with the request (session_id)
}

Response Types¶

1. 📑 Document Assistant¶

The Document Assistant can answer user questions using content from any financial or economic document that is indexed in Reflexivity. The assistant can read basic text and collect data from tables and charts.

Response

{
  source: "document-assistant";
  data: {
    message: string; // Message in response to user query focused around the documents returned
    citationsResult: {
      citations: Record<
        string,
        {
          title: string;
          url: string;
          pageNumber: number;
        }
      > | null;
    }
    citation_group_id: string;
    overview: {
      documents: number;
      companies: number;
      document_types: Record<
        // count of documents by types used to generate user response
        string,
        {
          count: number;
          relevance: number;
        }
      >;
      industries: Record<
        // count of documents by industry  used to generate user response
        string,
        {
          count: number;
          relevance: number;
        }
      >;
    }
  }
}

using citation_group_id the Citations service can be called to construct the document view below

https://api.reflexivity.com/citations/v1/group/<citation_group_id>/schemas
https://api.reflexivity.com/citations/v1/group/<citation_group_id>/documents
https://api.reflexivity.com/citations/v1/group/<citation_group_id>/filter

Document Message¶

Document view¶

document view

2. 🔮 Scenario Assistant¶

The Scenario Analysis Assistant allows you to test how a single or basket of assets have historically performed during any customized scenario. This assistant response is used in conjunction with Scenario Orchestrator service, which is used to run a scenario.

all data from response needs to be sent to https://api.reflexivity.com/scenario-orchestrator/v1/compass to get possible scenario outcomes

Response

{
  source: 'scenario-assistant';
  data: {
    conditions: Array<{
      snake: string;
      value: number;
      duration: number;
      duration_unit: string;
    }>;
    entities: Array<{
      id: string;
      tag: string;
    }>;
    actions?: Array<{
      action: 'scenario:run' | 'watchlist:create';
      display: string;
      data: Record<string, any>;
    }>;
  };
}

scenario

3. 📈 Chart Assistant¶

Chart Assistant is used for plotting any fundamental, technical or economic data series that Reflexivity holds within Calculator service.

Response

{
  source: 'chart-assistant';
  data: {
    assets: Array<{
      tag: string; // entity identifier
      snake: string;  // indicator identifier used to get time series
      is_default: boolean; // used to determine if asset is primary on chart
    }>; // the assets to plot time series for
    start?: string; // utc time stamp
    end?: string; // utc time stamp
    horizon?:  'OneDay' | 'OneWeek' | 'TwoWeeks' | 'OneMonth' | 'TwoMonths' | 'ThreeMonths' | 'SixMonths' | 'OneYear' | 'ThreeYears' | 'FiveYears' | 'TenYears' | 'Max' ;
    resample?:  '1D' | '1W' | '1M' | '1h' | '30m' | '15m' | '5m' | '1m';
    series_type?: 'line' | 'candlestick' | 'bars';
    y_axis_type?: 'split' | 'merged';
  };
}

Example response from alfred

{
  "source": "chart-assistant",
  "data": {
    "assets": [
      {
        "is_default": false,
        "snake": "aapl_nasd.pe_ibes_trailing_12m",
        "tag": "aapl_nasd"
      },
      {
        "is_default": false,
        "snake": "googl_nasd.pe_ibes_trailing_12m",
        "tag": "googl_nasd"
      }
    ],
    "confidence": 0.9998950958251953,
    "horizon": "ThreeMonths",
    "price_display": "price",
    "resample": "1D",
    "series_type": "line",
    "y_axis_type": "split"
  },
  "request_id": "7adbdd1c-d786-4c43-971f-56ced7db6df4"
}

chart embed

4. 📰 Fallback Assistant¶

The Fallback Assistant pulls from a general repository of financial sources like news and other web sources. After your question is sent to the assistant, the answer string is returned in markdown format, which may contain special links as below.

- [Investopedia](https://www.investopedia.com/dow-jones-today-04022025-11707447 \"article\")
- [MT Newswires](149530a5-7619-4812-8983-9f63f86b0c93 \"internal_news\")

Notice the third parameter in links when this is set to internal_news we use the id in the link to call Reflexivity's news service. Example: https://api.reflexivity.com/news/v3/149530a5-7619-4812-8983-9f63f86b0c93.

Response Schema

{
  source: "fallback-assistant";
  data: {
    answer: string;
  }
}

news message from alfred internal news

⚠️ Error Responses¶

1. Authentication Error¶

{
  status: 401;
  message: "Unauthorized";
}

2. Invalid Request¶

{
  status: 400;
  message: "Invalid request parameters";
}

🧪 Example Usage¶

Curl Request¶

curl -X POST 'https://api.example.com/alfred/v1/streaming' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
  "question": "What are Tesla's latest financial results?",
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "target": "document-assistant"
}'

📝 Notes¶

The API streams responses
Responses are chunked and each chunk is a complete JSON object
The stream ends with a completion signal or error
Rate limiting applies based on the user's subscription tier
All timestamps are in ISO 8601 format

🤝 Need Help?¶

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

Visit our help center: Getting started with Reflexivity
Contact Us: support@reflexivity.com