Smart Notes API QuickStart

The aim of this document is to provide developers with all the pieces of information they need to integrate Smart Notes to their platform.

Table of Contents

• Overview
• Authentication
• Read contents

Overview

Smart Notes APIs provide partners with the ability to integrate the data processed by Smart Notes in their own application.

To get access to the API you must first purchase a Smart Notes license.

Smart Notes APIs are based on the GraphQL Protocol.

The API endpoint is https://api.smart-notes.extrai.app/v1/graphql

The list of the available APIs and the exchanged models, can be accessed via GraphQL playground:

https://api.smart-notes.extrai.app/v1/graphql/playground

Authentication

All requests to Smart Notes APIs must be authenticated.

The APIs are exclusively meant to be used in a server to server environment, as they are authenticated via API Key.

Generate API Key

Login into Smart Notes Manager app, open the side menu and click on API, then follow the instructions to generate a new API key.

Read contents

Run queries via GraphQL Playground

1. Open the GraphQL Playground https://api.smart-notes.extrai.app/v1/graphql/playground
2. Add the API Key header in the bottom Headers input

   {
       "X-API-Key": "insertYourAPIKeyHere"
   }

3. Use the following queries to get the list of available contents or a single content

Get the list of contents

query getContents{
  getContents(pagination: {
    offset: 0
    first: 10
  }){
    totalCount
    edges{
      node{
        id
        name
        localizedName {
          name
          locale
        }
        data{
          ... on Lesson{
            speakers{
              name
              bio
            }
            keyPointsGenerationProcessStatus
            keyPointsTranslationProcessStatus
            keyPointsLocale
            keyPoints{
              title
              text
              localizedData{
                locale
                title
                text
              }
            }
          }
          ... on Talk{
            startAt
            speakers{
              name
              bio
            }
            keyPointsGenerationProcessStatus
            keyPointsTranslationProcessStatus
            keyPointsLocale
            keyPoints{
              title
              text
              localizedData{
                locale
                title
                text
              }
            }
          }
          ... on Panel {
            panelists {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            panelProcessStatus:processStatus
            startAt
            visibleHighlights {
              id
              title
              localizedTitle {
                locale
                title
              }
              panelistContributions {
                panelist {
                  id
                  originalAudioFileName
                  role
                  speaker {
                    id
                    name
                    bio
                    role
                  }
                }
                text
                localizedText {
                  locale
                  text
                }
              }
            }
            hiddenHighlights {
              id
              title
              localizedTitle {
                locale
                title
              }
              panelistContributions {
                panelist {
                  id
                  originalAudioFileName
                  role
                  speaker {
                    id
                    name
                    bio
                    role
                  }
                }
                text
                localizedText {
                  locale
                  text
                }
              }
            }
          }
          ... on GenericContent{
            genericContentProcessStatus:processStatus
            summary{
              text
              title
              localizedTitle{
                locale
                title
              }
              localizedText{
                locale
                text
              }
            }
          }
        }
        references{
          id
          url
          localizedDisplayText{
            locale
            displayText
          }
        }
      }
    }
    pageInfo{
      offset
      first
      scrollID
    }
  }
}

Get a single content

query getContent{
  getContent(contentID: "insertYourContentIDHere") {
    id
    name
    localizedName {
      name
      locale
    }
    data{
      ... on Lesson{
        speakers{
          name
          bio
        }
        keyPointsGenerationProcessStatus
        keyPointsTranslationProcessStatus
        keyPointsLocale
        keyPoints{
          title
          text
          localizedData{
            locale
            title
            text
          }
        }
      }
      ... on Talk{
        startAt
        speakers{
          name
          bio
        }
        keyPointsGenerationProcessStatus
        keyPointsTranslationProcessStatus
        keyPointsLocale
        keyPoints{
          title
          text
          localizedData{
            locale
            title
            text
          }
        }
      }
      ... on Panel {
        panelists {
          id
          originalAudioFileName
          role
          speaker {
            id
            name
            bio
            role
          }
        }
        panelProcessStatus:processStatus
        startAt
        visibleHighlights {
          id
          title
          localizedTitle {
            locale
            title
          }
          panelistContributions {
            panelist {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            text
            localizedText {
              locale
              text
            }
          }
        }
        hiddenHighlights {
          id
          title
          localizedTitle {
            locale
            title
          }
          panelistContributions {
            panelist {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            text
            localizedText {
              locale
              text
            }
          }
        }
      }
      ... on GenericContent{
        genericContentProcessStatus:processStatus
        summary{
          text
          title
          localizedTitle{
            locale
            title
          }
          localizedText{
            locale
            text
          }
        }
      }
    }
    references{
      id
      url
      localizedDisplayText{
        locale
        displayText
      }
    }
  }
}

Generate a token for external users to access the Embeddable Virtual Tutor

The embeddableVirtualTutorID can be found in the Smart Notes Manager app > Menu: Embed Virtual Tutor > Tab: Embedding > Click on: Copy Virtual Tutor ID.

The generated login token is valid for 1 hour. Once the Embeddable Virtual Tutor app has logged in via this token, the app will remain logged in regardless of the expiration of this token.

mutation genTokenForEmbeddableVirtualTutorGuest{
    genTokenForEmbeddableVirtualTutorGuest(
      embeddableVirtualTutorID: "insertYourEmbeddableVirtualTutorIDHere",
      externalUserID: "insertYourExternalUserIDHere"
  )
}

Run queries via Python

Get the list of contents

import requests

url = 'https://api.smart-notes.extrai.app/v1/graphql'
api_key = 'insertYourAPIKeyHere'

query = """
query getContents{
  getContents(pagination: {
    offset: 0
    first: 10
  }){
    totalCount
    edges{
      node{
        id
        name
        localizedName {
          name
          locale
        }
        data{
          ... on Lesson{
            speakers{
              name
              bio
            }
            keyPointsGenerationProcessStatus
            keyPointsTranslationProcessStatus
            keyPointsLocale
            keyPoints{
              title
              text
              localizedData{
                locale
                title
                text
              }
            }
          }
          ... on Talk{
            startAt
            speakers{
              name
              bio
            }
            keyPointsGenerationProcessStatus
            keyPointsTranslationProcessStatus
            keyPointsLocale
            keyPoints{
              title
              text
              localizedData{
                locale
                title
                text
              }
            }
          }
          ... on Panel {
            panelists {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            panelProcessStatus:processStatus
            startAt
            visibleHighlights {
              id
              title
              localizedTitle {
                locale
                title
              }
              panelistContributions {
                panelist {
                  id
                  originalAudioFileName
                  role
                  speaker {
                    id
                    name
                    bio
                    role
                  }
                }
                text
                localizedText {
                  locale
                  text
                }
              }
            }
            hiddenHighlights {
              id
              title
              localizedTitle {
                locale
                title
              }
              panelistContributions {
                panelist {
                  id
                  originalAudioFileName
                  role
                  speaker {
                    id
                    name
                    bio
                    role
                  }
                }
                text
                localizedText {
                  locale
                  text
                }
              }
            }
          }
          ... on GenericContent{
            genericContentProcessStatus:processStatus
            summary{
              text
              title
              localizedTitle{
                locale
                title
              }
              localizedText{
                locale
                text
              }
            }
          }
        }
        references{
          id
          url
          localizedDisplayText{
            locale
            displayText
          }
        }
      }
    }
    pageInfo{
      offset
      first
      scrollID
    }
  }
}
"""

headers = {
    'X-API-Key': api_key
}

response = requests.post(url, json={'query': query}, headers=headers)

if response.status_code != 200:
    print("HTTP response status code:", response.status_code)

print(response.text)

Get a single content

import requests

url = 'https://api.smart-notes.extrai.app/v1/graphql'
api_key = 'insertYourAPIKeyHere'
content_id = 'insertYourContentIDHere'

query = """
query getContent{
  getContent(contentID: "%s") {
    id
    name
    localizedName {
      name
      locale
    }
    data{
      ... on Lesson{
        speakers{
          name
          bio
        }
        keyPointsGenerationProcessStatus
        keyPointsTranslationProcessStatus
        keyPointsLocale
        keyPoints{
          title
          text
          localizedData{
            locale
            title
            text
          }
        }
      }
      ... on Talk{
        startAt
        speakers{
          name
          bio
        }
        keyPointsGenerationProcessStatus
        keyPointsTranslationProcessStatus
        keyPointsLocale
        keyPoints{
          title
          text
          localizedData{
            locale
            title
            text
          }
        }
      }
      ... on Panel {
        panelists {
          id
          originalAudioFileName
          role
          speaker {
            id
            name
            bio
            role
          }
        }
        panelProcessStatus:processStatus
        startAt
        visibleHighlights {
          id
          title
          localizedTitle {
            locale
            title
          }
          panelistContributions {
            panelist {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            text
            localizedText {
              locale
              text
            }
          }
        }
        hiddenHighlights {
          id
          title
          localizedTitle {
            locale
            title
          }
          panelistContributions {
            panelist {
              id
              originalAudioFileName
              role
              speaker {
                id
                name
                bio
                role
              }
            }
            text
            localizedText {
              locale
              text
            }
          }
        }
      }
      ... on GenericContent{
        genericContentProcessStatus:processStatus
        summary{
          text
          title
          localizedTitle{
            locale
            title
          }
          localizedText{
            locale
            text
          }
        }
      }
    }
    references{
      id
      url
      localizedDisplayText{
        locale
        displayText
      }
    }
  }
}
""" % (content_id)

headers = {
    'X-API-Key': api_key
}

response = requests.post(url, json={'query': query}, headers=headers)

if response.status_code != 200:
    print("HTTP response status code:", response.status_code)

print(response.text)

Generate a token for external users to access the Embeddable Virtual Tutor

The embeddableVirtualTutorID can be found in the Smart Notes Manager app > Menu: Embed Virtual Tutor > Tab: Embedding > Click on: Copy Virtual Tutor ID.

The generated login token is valid for 1 hour. Once the Embeddable Virtual Tutor app has logged in via this token, the app will remain logged in regardless of the expiration of this token.

import requests

url = 'https://api.smart-notes.extrai.app/v1/graphql'
api_key = 'insertYourAPIKeyHere'
embeddable_virtual_tutor_id = 'insertYourEmbeddableVirtualTutorIDHere'
external_user_id = 'insertYourExternalUserIDHere'

mutation = """
mutation genTokenForEmbeddableVirtualTutorGuest{
    genTokenForEmbeddableVirtualTutorGuest(
      embeddableVirtualTutorID: "%s",
      externalUserID: "%s"
  )
}
""" % (embeddable_virtual_tutor_id, external_user_id)

headers = {
    'X-API-Key': api_key
}

response = requests.post(url, json={'query': mutation}, headers=headers)

if response.status_code != 200:
    print("HTTP response status code:", response.status_code)

print(response.text)