API overview
API fundamentals
Each text analysis in the Smabbler API is a separate unit, which is identified by a unique OperationId. Currently, the API supports only a single text analysis per operation / request.
Text analysis using the Smabbler API is done asynchronously, by sending separate REST requests for initializing the analysis and acquiring the results separately.
Access to the API is granted via an API key, which is assigned to a Smabbler Portal Account. More details can be found in the API key section.
The analysis can be done using one of the pre-defined language models or a custom model built using Q-Lab.
There are certain API limits and quotas, which can be reviewed here.
API endpoints
Swagger API docs can be found in Smabbler Portal.
The Smabbler API has 4 endpoints divided into two groups:
/analyze
/analyze/initialize (POST) - used to initialize text analysis. Requires the text to be analyzed and a language model identifier as a parameter. Returns a unique OperationId analysis identifier.
/analyze/status (POST) - returns the status of the text analysis. Requires the OperationId identifier as a parameter. Click here to view the possible statuses.
/analyze/result (POST) - returns the result of the text analysis (if available). Requires the OperationId identifier as a parameter.
/algorithm
/algorithm/versions (GET) - returns a list of available pre-defined language models.
The base API url can be found in Smabbler Portal.
API key
Access to the Smabbler API is granted via an API Key. Each request must have an API key value set as x-api-key header value.
The API key is assigned to a Smabbler account and can be found in Smabbler Portal -> Account tab.
Please note that the API key is secret and must be treated appropriately to minimize the risk of leakage. However, if you suspect that your API key has been compromised, you can roll your API key. Key roll will invalidate the current one and generate new key value. API Key roll can be done in Smabbler Portal -> Account tab.
By default, API key has an infinite lifetime. It can be disabled in two cases:
if the key has been rolled
if the account subscription has expired or ended
How to get the API Key?
To get your API key go to the Account tab. The API key can be found in the API section.
If everything is OK, the key status should be Active. The key value can be viewed or copied using built-in buttons:
If your subscription is not active, the key may have the status unavailable or inactive:
How to roll the API Key?
If you suspect that your API key has leaked or been compromised, you should roll the key.
Doing so will invalidate your current API key and create a new one.
To roll API key open Account tab, and then in API section click on the ROLL API KEY button:
After clicking, a confirmation dialog will pop-up. If you are sure, please confirm the key roll:
After that, the key status will change to Pending for a few moments, until the new key becomes available:
Please note that the API key creation timestamp will also update, which can be used for key identification.
Analysis statuses
There are five valid analysis statuses:
initialized -> the analysis was initialized
assigned -> the analysis was assigned to a processing node and is waiting to be processed
processed -> the analysis was processed and results are waiting
failed -> the analysis failed due to a reason mentioned in the message part of the response
unknown -> the status of the analysis is unknown.
During normal operation, four statuses (initialized | assigned | processed | failed) are used to represent the state of the analysis.
The unknown status is given only in case of the most critical issues and usually requires contacting support.
Language models
The Smabbler API can be used to analyze text using a variety of language models, which are divided into two main groups:
pre-defined - ready-to-use language models prepared by Smabbler. The list of currently available language models can be obtained from /algorithm/versions endpoint
custom - custom language models, tailored to specific needs. These can be built using Q-lab.
The language model used for analysis can be set during the /analyze/initialize request under the algorithmVersion field. The possible value depends on model type:
for pre-defined models - use the model name returned from /versions endpoint
for custom model - use the unique model ID, which can be copied from Q-Lab Model list.
Limits and quotas
There are the following limits and quotas for API usage, depending on the access (API key) type:
for free early access:
max 10 requests per second
max 1 concurrent request
max 100000 requests per month
max analyzed text length (sent in the /analyze/initialize request) - 4000 characters
for paid regular access:
max 10 requests per second
max 1 concurrent request
max 100000 requests per month
max analyzed text length (sent in the /analyze/initialize request) - 4000 characters
Learn more about the free and regular access types here.
API billing
Currently the API billing depends on the API key (subscription type):
for free early access - API usage is free
for paid regular access - API usage costs as defined in the AWS Marketplace product.
Last updated