Getting started with our API
Welcome to Caravel's API documentation! Using Caravel's API you can
  • Predict topics and intents
  • Predict sentiment
  • Predict emotions
That's not all. With Caravel's API you can get granular. Send over any text document to our API, one by one or in bulk, and Caravel's API will pre-processes your text analyzing for sentiment, emotions, and classifications down to the sentence level.
You can use any classifier you build in your Caravel account with our API – giving you the ability to leverage our prebuilt models, zero-shot classification, and trainable classifiers in your own code!

Getting your key

  • Create your account and team on the Caravel Platform
  • Head over to your Workspace Settings by clicking on your team name in the left side nav.
  • Click on the Account tab
  • Click Generate Key and copy the key to your clipboard
This is the key you will use to make calls to Caravel's API. If at anytime you need a new key, click Regenerate Key and it will deactivate your old key and give you a new one.

Predicting sentiment

Our API provides a global endpoint you can use if you only want to classify sentiment.
post
/v1/sentiment
Classify Sentiment
cURL
Python
Node
1
curl --location --request POST 'https://api.caravelapp.com/v1/sentiment' \
2
--header 'X-Api-Key: YOUR API KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"texts": [
6
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
7
]
8
}'
Copied!
1
import http.client
2
import json
3
4
conn = http.client.HTTPSConnection("api.caravelapp.com")
5
payload = json.dumps({
6
yth "texts": [
7
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
8
]
9
})
10
headers = {
11
'X-Api-Key': 'YOUR API KEY',
12
'Content-Type': 'application/json'
13
}
14
conn.request("POST", "/v1/sentiment", payload, headers)
15
res = conn.getresponse()
16
data = res.read()
17
print(data.decode("utf-8"))
Copied!
1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://api.caravelapp.com/v1/sentiment',
5
'headers': {
6
'X-Api-Key': 'YOUR API KEY',
7
'Content-Type': 'application/json'
8
},
9
body: JSON.stringify({
10
"texts": [
11
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
12
]
13
})
14
15
};
16
request(options, function (error, response) {
17
if (error) throw new Error(error);
18
console.log(response.body);
19
});
20
Copied!

Predicting emotions

We also provide a similar global endpoint for predicting just emotions.
post
/v1/emotions
Classify Emotions
cURL
Python
Node
1
curl --location --request POST 'https://api.caravelapp.com/v1/emotions' \
2
--header 'X-Api-Key: YOUR API KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"texts": [
6
"Is there a button to raise/lower hand? It would come in handy in the Safe Driving Mode page."
7
]
8
}'
Copied!
1
import http.client
2
import json
3
4
conn = http.client.HTTPSConnection("api.caravelapp.com")
5
payload = json.dumps({
6
"texts": [
7
"Is there a button to raise/lower hand? It would come in handy in the Safe Driving Mode page."
8
]
9
})
10
headers = {
11
'X-Api-Key': 'YOUR API KEY',
12
'Content-Type': 'application/json'
13
}
14
conn.request("POST", "/v1/emotions", payload, headers)
15
res = conn.getresponse()
16
data = res.read()
17
print(data.decode("utf-8"))
Copied!
1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://api.caravelapp.com/v1/emotions',
5
'headers': {
6
'X-Api-Key': 'YOUR API KEY',
7
'Content-Type': 'application/json'
8
},
9
body: JSON.stringify({
10
"texts": [
11
"Is there a button to raise/lower hand? It would come in handy in the Safe Driving Mode page."
12
]
13
})
14
15
};
16
request(options, function (error, response) {
17
if (error) throw new Error(error);
18
console.log(response.body);
19
});
Copied!

Predicting topics and intents with a Classifier

You can create your own text classifiers that you can use with Caravel's API to predict topics and intents.
post
/v1/classifiers/{classifier_id}
Classify

Creating a Classifier

There are two type of text classifiers: Ensembles and Tags.
Ensembles classify without training data. With Ensembles you can combine any of the following techniques to classify text: keyword matching, prebuilt machine learning models, sentiment matching, and zero-shot classification (also known as inference).
Use Tag Classifiers to annotate text in your feed to train a classifier.
We offer a myriad of prebuilt classifiers in our library to help you get started right away.
Once you've created a classifier, you'll need the Classifier ID to use it with our API. Copy and paste the Classifier ID from the URL in your browser's address bar.

Using your Classifier in the API

Be sure to input your Classifier ID and API Key in the follow examples.
cURL
Python
Node
1
curl --location --request POST 'https://api.caravelapp.com/v1/classifiers/YOUR-CLASSIFIER-ID' \
2
--header 'X-Api-Key: YOUR API KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"texts": [
6
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
7
]
8
}'
Copied!
1
import http.client
2
import json
3
4
conn = http.client.HTTPSConnection("api.caravelapp.com")
5
payload = json.dumps({
6
"texts": [
7
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
8
]
9
})
10
headers = {
11
'X-Api-Key': 'YOUR API KEY',
12
'Content-Type': 'application/json'
13
}
14
conn.request("POST", "/v1/classifiers/YOUR-CLASSIFIER-ID", payload, headers)
15
res = conn.getresponse()
16
data = res.read()
17
print(data.decode("utf-8"))
Copied!
1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://api.caravelapp.com/v1/classifiers/YOUR-CLASSIFIER-ID',
5
'headers': {
6
'X-Api-Key': 'YOUR API KEY',
7
'Content-Type': 'application/json'
8
},
9
body: JSON.stringify({
10
"texts": [
11
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
12
]
13
})
14
15
};
16
request(options, function (error, response) {
17
if (error) throw new Error(error);
18
console.log(response.body);
19
});
20
Copied!

Classifying in bulk

If you need to classify more than one piece of text at a time, Caravel's API accepts multiple documents in the texts parameter. Each document is classified asynchronously for high-speed performance when working with bulk data and the results are returned once all documents have been classified.
Bulk classification is limited to 50 text documents at a time. If you need to classify more than this per request, please contact our support team at [email protected].
To classify in bulk, simply input multiple text documents into the texts array in your request:
cURL
Python
Node
1
curl --location --request POST 'https://api.caravelapp.com/v1/classifiers/290c5812-3acf-47b3-928b-2ecc8c966d25' \
2
--header 'X-Api-Key: fyMxf8eKa0DL18znJq5SB6N5S64' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"texts": [
6
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
7
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
8
"Super app but viratual brackgroud cant use is in mobile version please arrange it. but i gave 5stares",
9
"Good app. Yay 👍. I gave a review and the developers team looked into the review and enabled the host and co host to raise hands. Now one more thing, a raise/lower hand button would come in handy in the Safe Driving Mode page.",
10
"This app works only on Pc browser...can'\''t use it on phone, only while using desktop browser mode.. waste of time for majority"
11
]
12
}'
Copied!
1
import http.client
2
import json
3
4
conn = http.client.HTTPSConnection("api.caravelapp.com")
5
payload = json.dumps({
6
"texts": [
7
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
8
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
9
"Super app but viratual brackgroud cant use is in mobile version please arrange it. but i gave 5stares",
10
"Good app. Yay 👍. I gave a review and the developers team looked into the review and enabled the host and co host to raise hands. Now one more thing, a raise/lower hand button would come in handy in the Safe Driving Mode page.",
11
"This app works only on Pc browser...can't use it on phone, only while using desktop browser mode.. waste of time for majority"
12
]
13
})
14
headers = {
15
'X-Api-Key': 'fyMxf8eKa0DL18znJq5SB6N5S64',
16
'Content-Type': 'application/json'
17
}
18
conn.request("POST", "/v1/classifiers/290c5812-3acf-47b3-928b-2ecc8c966d25", payload, headers)
19
res = conn.getresponse()
20
data = res.read()
21
print(data.decode("utf-8"))
Copied!
1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://api.caravelapp.com/v1/classifiers/YOUR-CLASSIFIER-ID',
5
'headers': {
6
'X-Api-Key': 'YOUR API KEY',
7
'Content-Type': 'application/json'
8
},
9
body: JSON.stringify({
10
"texts": [
11
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
12
"Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other.",
13
"Super app but viratual brackgroud cant use is in mobile version please arrange it. but i gave 5stares",
14
"Good app. Yay 👍. I gave a review and the developers team looked into the review and enabled the host and co host to raise hands. Now one more thing, a raise/lower hand button would come in handy in the Safe Driving Mode page.",
15
"This app works only on Pc browser...can't use it on phone, only while using desktop browser mode.. waste of time for majority"
16
]
17
})
18
19
};
20
request(options, function (error, response) {
21
if (error) throw new Error(error);
22
console.log(response.body);
23
});
24
Copied!

Getting segments

Caravel's API makes fine-grain text analysis easy, enabling you to get the sentiment, emotions, and classified topics and intents of every sentence in a text document. Simply pass in include_segments option to get sentence level insights and Caravel returns all your classifications down to the sentence.
cURL
Python
Node
1
curl --location --request POST 'https://api.caravelapp.com/v1/classifiers/YOUR-CLASSIFIER-ID' \
2
--header 'X-Api-Key: YOUR API KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"texts": [
6
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
7
],
8
"include_segments": true
9
}'
Copied!
1
import http.client
2
import json
3
4
conn = http.client.HTTPSConnection("api.caravelapp.com")
5
payload = json.dumps({
6
"texts": [
7
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
8
],
9
"include_segments": True
10
})
11
headers = {
12
'X-Api-Key': 'YOUR API KEY',
13
'Content-Type': 'application/json'
14
}
15
conn.request("POST", "/v1/classifiers/YOUR-CLASSIFIER-ID", payload, headers)
16
res = conn.getresponse()
17
data = res.read()
18
print(data.decode("utf-8"))
Copied!
1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://api.caravelapp.com/v1/classifiers/YOUR-CLASSIFIER-ID',
5
'headers': {
6
'X-Api-Key': 'YOUR API KEY',
7
'Content-Type': 'application/json'
8
},
9
body: JSON.stringify({
10
"texts": [
11
"It’s hard to remember now, but there was a time, in the not-too-distant past, when people didn’t utter the phrase “go on mute” every single day. That’s just one of the ways Zoom has changed the landscape/society/fabric of space-time; what started as a videoconferencing app for business has become our go-to way (and word) for connecting with people in other places. Zoom’s meteoric rise came due to timing and circumstance, sure, but the app has met its moment with an elegant design, reliable performance, and constantly evolving features. But in the end, its real meaning is bigger: Zoom keeps us connected with each other."
12
],
13
"include_segments": true
14
})
15
16
};
17
request(options, function (error, response) {
18
if (error) throw new Error(error);
19
console.log(response.body);
20
});
21
Copied!