About SensaAI's APIs

SensaAI provides two APIs: a REST API and a GraphQL API.

Overview

SensaAI provides two APIs: a REST API and a GraphQL API. You can interact with both APIs using curl or using requests module available for most popular programming languages (our docs currently provide code examples for Python and NodeJS) . Occasionally, a feature may be supported on one API but not the other.

You should use the API that best aligns with your needs and that you are most comfortable using. You don't need to exclusively use one API over the other.

This article discusses the benefits of each API. For more information about the GraphQL API, see About the GraphQL API.. For more information about the REST API, see About the REST API..

Choosing the GraphQL API

The GraphQL API returns exactly the data that you request. GraphQL also returns the data in a pre-known structure based on your request. In contrast, the REST API returns more data than you requested and returns it in a pre-determined structure. You can also accomplish the equivalent of multiple REST API request in a single GraphQL request. The ability to make fewer requests and fetch less data makes GraphQL appealing to many users.

For example, to get the all watchlists for a user and the first 10 stocks in each watchlist you can send a single request like:

query {
  watchlistsForUser {
    id
    name
    description
    watchlistItems(first: 10) {
      edges {
        node {
          stock {
            id
            name
            ticker
          }
        }
      }
    }
  }
}

The response will be a JSON object that follows the structure of your request.

In contrast, to get this same information from the REST API, you would need to first make a request to GET "/data/v1/watchlists. The API would return the id of each watchlist, along with other data about the watchlists that you don't necessarily need. Then, for each watchlist, you would need to make a request to GET "/data/v1/watchlist_items/:id.

Choosing the REST API

Because REST APIs have been around for longer than GraphQL APIs, some users are more comfortable with the REST API. Since REST APIs use standard HTTP verbs and concepts, many users are already familiar with the basic concepts to use the REST API.

For example, if you already know the id of the object you wish to retrieve and you are happy with the predefined return content, you can make a simple HTTP request. For example to retrieve details of a portfolio with id 332 you could simply send the following HTTPS request: GET "/data/v1/portfolios/332?api_key=API_KEY" which would return an object like:

{
  "id": "332",
  "owner": {
    "id": "1"
  },
  "name": "Quality - Top 50",
  "description": "This portfolio consists of the top 50 stocks with an above 7 rating for Return, Growth and Risk. Portfolio is rebalanced once a quarter.",
  "private": false,
  "createdAt": "2020-06-21T16:17:38.893462+00:00",
  "rebalanceFrequency": 3,
  "maxStocks": 50,
  "maxStocksCriteria": "total_rating",
  "maxStocksCriteriaOrder": "descending",
  "nextRebalanceDate": "2021-01-02",
  "previousRebalanceDate": "2020-10-02",
  "ranges": {
    "returnRating": [
      7.0,
      10.0
    ],
    "growthRating": [
      7.0,
      10.0
    ],
    "riskRating": [
      7.0,
      10.0
    ]
  }
}

In contrast, to retrieve the same object with the same response content in the GraphQL API you would need to construct a query similar to below:

query portfoliosForUser {
  portfoliosForUser(id: 332) {
    id
    owner {
      id
    }
    name
    description
    private
    createdAt
    rebalanceFrequency
    maxStocks
    maxStocksCriteria
    maxStocksCriteriaOrder
    nextRebalanceDate
    previousRebalanceDate
    ranges
  }
}