Contextual provides a platform for creating enterprise-grade AI agents, grounded in your documents and data. See a demo of our agents here.
Our APIs provide powerful—yet simple—interfaces for ingesting data, creating agents, and interacting with our state-of-the-art Contextual RAG system.
Follow this guide to create your first agent!
Get your API Key
If you do not have access to the platform, you can request an API key via the Request Access button in the header of the documentation page or on the Contextual website.
Contextual uses API keys to authenticate requests. Only admins within a tenant can create API keys. To create a key:
- Log into your tenant at app.contextual.ai
- Click on API Keys in the sidebar
- Click the Create API Key button in the upper right and follow the instructions
- Save the generated key in a secure location
Via curl commands
Step 1: Create a datastore
A datastore securely stores the files you would like to search and reference in your agents. Each agent must be associated with at least one datastore. You can create a datastore 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"}'
Note: Remember to replace $API_KEY
with your key and feel free to rename the datastore
If the request is successful, the id
of the newly created datastore will be returned to you. Be sure to save this id
as you will need it in subsequent steps!
Step 2: Upload documents into your datastore
Now that you've created a datastore, you can start uploading documents into the platform. Uploaded documents are processed by Contextual in ways optimized for retrieval.
- If you don't have your own documents handy, feel free to use our test documents, found here
- For the best experience, please use renderable PDFs
You can upload a document 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}'
Note: Remember to:
- Replace
{datastore_id}
in the url path with theid
from the previous step - Replace
$API_KEY
with your API key - Replace
{file_path}
with the path to the document on your machine
If the request is successful, the id
of the uploaded document will be returned to you. Keep in mind that a given document may require a few minutes to fully process once uploaded.
To check the status of documents uploaded into the datastore, use this command:
curl --request GET \
--url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
--header 'accept: application/json' \
--header 'authorization: Bearer $API_KEY'
Note: Remember to:
- Replace
{datastore_id}
in the url path with theid
from the previous step - Replace
$API_KEY
with your API key
You should see the document you uploaded in the list, along with its ingestion_job_status
.
Step 3: Create an agent
Now that you have a datastore with some files, you can use the /agents
endpoint to create your first agent.
curl --request POST \
--url https://api.contextual.ai/v1/agents \
--header 'accept: application/json' \
--header 'authorization: Bearer $API_KEY' \
--header 'content-type: application/json' \
--data '
{
"name": "Test",
"description": "Test Agent",
"datastore_ids": []
}
'
Note: Remember to:
- Replace
$API_KEY
with your API key - Populate the
datastore_ids
list field with the datastoreid
from above
If the request is successful, the agent_id
of the newly created agent will be returned to you. You'll need this to query your agent in the next step.
Step 4: Query your agent
Now that you've set up an agent and uploaded documents for use with it, you can use the /query
endpoint to send messages:
curl --request POST \
--url https://api.contextual.ai/v1/agents/{agent_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 the revenue of Apple?"
}
]
}
'
Note: Remember to:
- Replace
{agent_id}
in the url path with the agent_id from the previous step - Replace
$API_KEY
with your API key - Replace the
content
field with a question that is relevant to the document(s) you uploaded
If the request is successful, you'll receive a response back that will contain:
- The body of the response
- The sources retrieved from the datastore that are relevant to the response
- Attributions/citations of sources to specific text spans in the response
Note: You should wait to query your agent until at least one document in the datastore has finished processing. You can check the status of uploaded documents by following the instructions in the previous step.
🙌 Congrats! You've now created a basic agent in the Contextual platform, interacted with it, and evaluated its results.
Via Contextual API Docs
As an alternative to shell commands, you can also use the interactive areas of our documentation to interact with our APIs .
Step 1: Create a Datastore
To create a datastore via the API docs:
- Expand the /datastores section in the sidebar
- Select Create Datastore
- Enter the name of your datastore in the Body Params field in the central panel
- Input your API key in the Bearer field in the top of the right panel
- Click the Try It! button
- Save the returned datastore
id
for future reference
Step 2: Upload documents into your datastore
To upload a document:
- Expand the /datastores section in the sidebar
- Select Ingest Document
- Enter the datastore id from the previous step in the
datastore_id
field - Click the upload button in the
file
field to select a file from your local machine for upload - Input your API key in the Bearer field in the top of the right panel
- Click the Try It! button
Keep in mind that processing the document after upload can take a few minutes. To check the status of your uploaded document(s):
- Expand the Datastores section in the sidebar
- Select List Document
- Enter the datastore id in the
datastore_id
field - Input your API key in the Bearer field in the top of the right panel
- Click the Try It! button
Step 3: Create an agent
To create an agent linked to the datastore you created:
- Expand the /agents section in the sidebar
- Select Create Agent
- Input a name and description in the respective fields in the central panel
- Click Add String in the
datastore_ids
field and input thedatastore_id
from earlier - Input your API key in the Bearer field in the top of the right panel
- Click the Try It! button
If successful, you will see a 200
response and the agent should also appear in your tenant. Save the returned agent id for the query step.
Step 4: Query your agent
To send a message to your agent:
- Expand the /agents/{id}/query section in the sidebar
- Select Query
- Input the id from the prior step in the
agent_id
field - Click Add Object in the
messages
field and type a question that is relevant to the given document(s) you uploaded in the content field - Input your API key in the Bearer field in the top of the right panel
- Click the Try It! button
If successful, you'll see a 200
response, the body of which will contain:
- The body of the response
- The sources retrieved from the datastore that are relevant to the response
- Attributions/citations of sources to specific text spans in the response
WHAT'S NEXT
Now that you've covered the basics, feel free to explore our advanced features, including evaluation and tuning options, for deeper insights into your agent.