Copilot APIData API

Custom Data

By defining API endpoints hosted on their own web servers, clients can enable Copilot to access and use custom datasets in real-time. This allows for highly tailored insights, drawing on internal data sources to enhance the bot’s capabilities and provide more personalized and relevant responses to users.

This documentation outlines how to structure your API endpoint’s data to ensure compatibility with our platform. Below, you’ll find an overview of the key elements your API should support, followed by a breakdown of each data type and structure required.

OverviewCopied!

When integrating your API with our platform, the data you return must conform to specific schemas to be correctly interpreted and displayed. These schemas are built using zod types, which enforce the structure and types of the data expected by our platform.

Key ComponentsCopied!

  • Context: High-level description provided to the LLM.

  • Card: The main data structure used for displaying information in the UI, containing various types of sources (PDF, text, data, etc.).

    • Source: Data or content displayed within a card, such as charts, tables, PDFs, or text.

    • Controls Settings: Configuration options that allow users to interact with and manipulate the data displayed.

API Response Structure Copied!

Your API should return a JSON object structured as follows:

{
  "context": "string",  // High-level context description for the LLM
  "card": {
    "title": "string",  // Title of the card
    "logo": "string (optional)",  // URL to the logo image (optional)
    "source": "string (optional)",  // Source URL (optional)
    "sources": [
      // Insert specific source type here (PDF, Text, or Data - see below for structures)
    ]
  }
}

Rendering a PDFCopied!

Use this structure if your card needs to display a PDF document.

{
  "type": "PDF",
  "pdfUrl": "string"  // URL to the PDF file
}

Example:

{
  "type": "PDF",
  "pdfUrl": "https://example.com/document.pdf"
}

Rendering TextCopied!

Use this structure if your card needs to display plain text content. This will be rendered using Markdown.

{
  "type": "Text",
  "text": "string"  // The text content to be displayed
}

Example:

{
  "type": "Text",
  "text": "This is a detailed analysis of the financial data."
}

Rendering a Data VisualizationCopied!

Use this structure if your card needs to display data in a chart or table format.

{
  "type": "Data",
  "view": {
    "chart": true,  // Boolean to display a chart
    "table": true  // Boolean to display a table
  },
  "toolbar": {  // Optional user controls for data interaction
    "showDataLabels": {
      "enabled": true,
      "defaultValue": true
    },
    "decimalPlaces": {
      "enabled": true,
      "defaultValue": 2,
      "upperBound": 4,
      "lowerBound": 0
    },
    "currency": {
      "enabled": true,
      "defaultValue": "USD",
      "options": ["USD", "EUR", "GBP"]
    },
    "period": {
      "enabled": true,
      "defaultValue": "Quarterly",
      "options": ["Annual", "Quarterly", "Semi-Annual", "LTM"]
    },
    "magnitude": {
      "enabled": true,
      "defaultValue": "M",
      "options": ["K", "M", "B"]
    },
    "reverseDataOrder": {
      "enabled": true,
      "defaultValue": false
    },
    "timeframe": {
      "enabled": true,
      "defaultValue": "5Y",
      "options": ["3Y", "5Y", "10Y", "MAX"]
    }
  },
  "datasets": [  // Array of datasets
    {
      "label": "string",  // Label for the dataset
      "data": [  // Array of data points
        {
          "date": "YYYY-MM-DD",  // Date in the format "YYYY-MM-DD"
          "value": 100,  // Numeric value
          "label": "string (optional)"  // Optional label for the data point
        }
      ],
      "timeframe": "3Y" | "5Y" | "10Y" | "MAX",  // Timeframe for the data
      "period": "Annual" | "Quarterly" | "Semi-Annual" | "LTM",  // Period for the data
      "dateFormat": "string (optional)",  // Format for the date strings
      "valueFormat": "number" | "ratio" | "% (optional)",  // Format for the values
      "currency": "string (optional)",  // Currency for the data values
      "chartOptions": {  // Optional chart-specific settings
        "chartType": "line" | "column",
        "isStacked": true,  // Boolean for stacked columns
        "separateAxisId": "string (optional)"  // Axis ID for separate axis
      }
    }
  ],
  "customColors": ["#FF5733", "#33FF57"]  // Optional custom colors for the chart
}

Example:

{
  "type": "Data",
  "view": {
    "chart": true,
    "table": true
  },
  "toolbar": {
    "showDataLabels": {
      "enabled": true,
      "defaultValue": true
    },
    "decimalPlaces": {
      "enabled": true,
      "defaultValue": 2,
      "upperBound": 4,
      "lowerBound": 0
    },
    "currency": {
      "enabled": true,
      "defaultValue": "USD",
      "options": ["USD", "EUR", "GBP"]
    },
    "period": {
      "enabled": true,
      "defaultValue": "Quarterly",
      "options": ["Annual", "Quarterly", "Semi-Annual", "LTM", "Daily"]
    },
    "magnitude": {
      "enabled": true,
      "defaultValue": "M",
      "options": ["K", "M", "B"]
    },
    "reverseDataOrder": {
      "enabled": true,
      "defaultValue": false
    },
    "timeframe": {
      "enabled": true,
      "defaultValue": "5Y",
      "options": ["3Y", "5Y", "10Y", "MAX"]
    }
  },
  "datasets": [
    {
      "label": "Revenue",
      "data": [
        { "date": "2021-01-01", "value": 100, "label": "Q1 2021" },
        { "date": "2021-04-01", "value": 150, "label": "Q2 2021" }
      ],
      "timeframe": "5Y",
      "period": "Quarterly",
      "valueFormat": "number",
      "currency": "USD",
      "chartOptions": {
        "chartType": "line",
        "isStacked": false
      }
    }
  ],
  "customColors": ["#FF5733", "#33FF57"]
}

Setup & Configuration on FinChatCopied!

From your organization’s settings, open the Partner Portal

FunctionCopied!

  • Name: Descriptive name for the function.

  • Description: A brief explanation of the function.

  • Endpoint: The endpoint where the data is hosted in a structured format (see type definition below), allowing the function to access and retrieve the necessary information.

ParametersCopied!

Parameters are generated by Copilot to answer the user query. They are then passed to your endpoint for processing.

  • Name: A descriptive name of the parameter.

  • Type: Whether the parameter is a string, number, or boolean.

  • List of Valid Inputs: If applicable for string or number you can constrain values to be within this list.

  • Required: Whether this parameter is optional for the LLM to generate.

  • Description: A brief description of the parameter, including examples.

ExampleCopied!

Let’s say you have sentiment data you want to bring in for stocks. You can define a getStockSentiment function:

  • Function

  • Parameters

    • Parameter 1

      • Name: publicly_traded_company_name_or_ticker

      • Type: string

      • Required: true

      • Description: The name or ticker of the publicly traded company to query.

If someone asked for sentiment data on Apple, Copilot will send a POST request to https://api.finchat.io/getStockSentiment with the body of { “publicly_traded_company_name_or_ticker”: “Apple” }. You can then either match this against your own search engine or use our company matching endpoint in this case since it’s a publicly traded company. You then retrieve the data from your database and format it for the LLM to understand and return cards to be displayed like a chart of the sentiment over time.

This API documentation is provided by FinChat. For assistance, or feedback contact our support team and for inquiries or if you want to learn more contact our sales team.

© 2024 FinChat