Insightfol.io API
Last updated

Insightfol.io API

This API allows clients to manage portfolios, analyze them, and retrieve detailed results. The API includes endpoints for managing portfolios, adding positions, starting analysis, and retrieving analysis results.

Base URL

https://insightfol.io/api

Authentication

All endpoints require an API key, passed in the request headers as:

X-API-Key: <your_api_key>

Endpoints

1. Get Instrument Info

GET /instruments/{country}/{instrument_id}/

Retrieve details of a specific instrument.

  • Parameters:

    • country (string): The country code of the instrument (e.g., US).
    • instrument_id (string): The ISIN of the instrument.

  • Response Example:

{
  "isin": "US0378331005",
  "symbol": "AAPL.NASDAQ",
  "country": "US",
  "type": "Equity",
  "name": "Apple Inc."
}

2. Create Portfolio

POST /portfolios/

Create a new portfolio for the client.

  • Request Body:
{
  "name": "Retirement Fund",
  "region": "US",
  "positions": [
    {
      "instrumentId": "US0378331005",
      "country": "US",
      "allocation": 20.5
    }
  ]
}
  • Response Example:
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Retirement Fund",
  "region": "US",
  "positions": [...],
  "analysis_status": "NOT_STARTED"
}

3. Add or Update Positions in Portfolio

POST /portfolios/{portfolio_id}/positions/

Add or update positions in a portfolio.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Request Body:

{
  "positions": [
    {
      "instrumentId": "US0378331005",
      "country": "US",
      "allocation": 20.5
    }
  ]
}
  • Response Example:
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Retirement Fund",
  "region": "US",
  "positions": [...],
  "analysis_status": "NOT_STARTED"
}

4. Start Portfolio Analysis

POST /portfolios/{portfolio_id}/analyze/

Start the analysis of a portfolio. Portfolio positions must sum to 100%.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Query Parameters:

    • language (string): Optional. One of en, de, or es.

  • Response Example:

{
  "message": "Analysis started"
}

5. Get Analysis Status

GET /portfolios/{portfolio_id}/analysis/status/

Retrieve the current analysis status of a portfolio.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Response Example:

{
  "analysis_status": "IN_PROGRESS"
}

6. Get Analysis Allocations

GET /portfolios/{portfolio_id}/analysis/results/allocations/

Retrieve the allocation results of a completed portfolio analysis.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Response Example:

{
  "US": 60,
  "DE": 20,
  "FR": 20
}

7. Get Ex-Post Analysis

GET /portfolios/{portfolio_id}/analysis/results/expost/

Retrieve the ex-post performance metrics of a portfolio.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Response Example:

{
  "return": 5.6,
  "volatility": 12.3
}

8. Get Forward-Looking Analysis (Ex-Ante)

GET /portfolios/{portfolio_id}/analysis/results/exante/

Retrieve forward-looking (ex-ante) analysis results of a portfolio.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Response Example:

{
  "expected_return": 7.2,
  "expected_risk": 10.8
}

9. Get AI-Generated Report

GET /portfolios/{portfolio_id}/analysis/results/ai/

Retrieve an AI-generated report for a portfolio.

  • Parameters:

    • portfolio_id (string): The ID of the portfolio.

  • Response Example:

{
  "summary": "The portfolio is well-diversified across sectors."
}

Common Responses

  • 200 OK: The request was successful.
  • 400 Bad Request: Invalid input or missing required fields.
  • 403 Forbidden: API key is missing or invalid.
  • 404 Not Found: Resource not found (e.g., portfolio, instrument).
 
Next page