API Reference
Request Access

Beginner's Guide

Contextual’s APIs provide a simple interface to state-of-the-art CLMs. Use this guide to learn the basics of creating your first application programmatically to interact with your data . You can access the full suite of API functionality @ docs.contextual.ai

API key

To begin, you will need an API key to securely access the API. To generate an API key, your admin can follow the process below:

  1. Log into your tenant at app.contextual.ai
  2. Click on "API Keys"
  3. Click on "Create API Key"
  4. Please keep your key in a secure place, and do not share it with anyone

Creating your first Application (using Python)

To help you get started quickly, we provide this interactive Python notebook (Jupyter notebook) that demonstrates key features and example usages of the platform. This hands-on resource enables you to explore the platform's capabilities interactively, making it easier to understand how you can create an application, ingest documentation, and make a query request.

Creating your first Application (using Terminal)

Follow the below steps below to create your first application via terminal.

1. Creating a Datastore

A datastore is secure storage for application data. Each application requires a datastore that is managed by a user. You can create a datastore for your application using the /datastores endpoint with the following command:


curl --request POST \
     --url https://api.contextual.ai/v1/datastores \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY' \
     --header 'content-type: application/json' \
     --data '
     {"name":"Test Datastore"}
		'

You can check if the datastore was successfully created using the /datastores endpoint with the following command:

curl --request GET \
     --url 'https://api.contextual.ai/v1/datastores?limit=10' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY'

2. Ingesting documents into your Datastore

Now that you have created a datastore, you can start ingesting documents into your application’s datastore also using the /datastores endpoint.

You can use your own documents or use our provided test documents here. For the best experience, please use renderable PDFs. You can ingest documents using the following command:

curl --request POST \
     --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY' \
     --header 'content-type: multipart/form-data' \
     --form file='$file_path'

Keep in mind that document ingestion may take a few minutes.

You can check if your documents were successfully ingested using the using the /datastores endpoint with the following command:

curl --request GET \
     --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
     --header 'accept: application/json'
     --header 'authorization: Bearer $API_KEY' \

3. Creating an Application

Now that the datastore for your application is prepared, you can use /application endpoint to create your application and link it to the datastore using the following command:

curl --request POST \
     --url https://api.contextual.ai/v1/applications \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY' \
     --header 'content-type: application/json'
     --data '
{
  "name": "Test",
  "description": "Test Application"
}
'

Your application should appear in your tenant on app.contextual.com. You can also use /application endpoint to check if the application was successfully created by using the following command:

curl --request GET \
     --url 'https://api.contextual.ai/v1/applications?limit=1000' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY'

4. Query

Now that you have created a datastore, ingested documents, and created an application, you can start a conversation with your application using the /query endpoint. Use the following command: 

curl --request POST \
     --url https://api.contextual.ai/v1/applications/{application_id}/query \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "What is Apple's revenue?"
    }
  ]
}
'


Creating your first Application (using docs.contextual.ai)

Go to API Reference and select the relevant actions from the menu below:

1. Creating a Datastore

You can create a datastore by using Create Datastore option under Datastores.

Once you have created a datastore you can check if the datastore was successfully created with the List Datastores option under Datastores.

2. Ingesting documents into your Datastore

You can ingest documents into your datastore by using Ingest Document option under Datastores.

Keep in mind that document ingestion may take a few minutes. You can check if your documents were successfully ingested using List Documents option under Datastores.

3. Creating an Application

Now that the datastore for your application is prepared, you can create your application and link it to the datastore using Create Application option under Applications.

Your application should appear in your tenant on app.contextual.com. You can also check if the application was successfully created using List Applications option under Applications.

4. Query

Now that you have created a datastore, ingested documents, and created an application, you can start a conversation with your application using Query.