API guide

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 your custom built model.

  • There are certain API limits and quotas.

API endpoints

The Smabbler API has 18 endpoints divided into 5 groups:

  • /source

    • /source/file (POST)

      • Uploads a new source (e.g., text or CSV file) for analysis.

      • Parameters:

        • SourceFile (required): The file to upload. It must be in .txt or .csv format.

      • A response containing a unique identifier of the source: sourceId.

    • /source/{sourceId} (GET)

      • Retrieves details for a specific source, such as its ID and Status.

      • Parameters:

        • sourceId: The unique identifier of the source to retrieve.

    • /sources (GET)

      • Retrieves a paginated list of all available sources.

      • Parameters:

        • page (query, optional): Page number (default: 0).

        • pageSize (query, optional): Number of items per page (default: 10).

        • status (query, optional): Source status, case-sensitive.

      • Returns a list of source objects containing: sourceId and status of the source.

    • /source/{sourceId}/analyze/txt (POST)

      • Initiates a text analysis operation for the specified source.

      • Parameters:

        • sourceId: Identifier of the source to analyze.

    • /source/{sourceId}/analyze/csv (POST)

      • Analyzes the content of a CSV source with specific column configurations.

      • Parameters:

        • sourceId: Identifier of the source to analyze.

        • idColumnName (body): Name of the column containing unique IDs.

        • textColumnNames (body): List of column names containing text to analyze (comma-separated).

    • /source/{sourceId} (DELETE)

      • Deletes the given source permanently.

      • Parameters:

        • sourceId: Identifier of the source to delete.

  • /model

    • /model/build (POST)

      • Builds a custom model using the provided sources.

      • Parameters:

        • sourceIds (body): List of analyzed source identifiers (coma separated) to use for building the model.

        • modelName (body): Name of the model to create.

      • Returns new model identifier.

    • /model/{modelId} (GET)

      • Retrieves details about a specific custom model, e.g. status, name.

      • Parameters:

        • modelId: Unique identifier of the model to retrieve.

    • /models (GET)

      • Retrieves a list of all available custom models.

      • Parameters:

        • page (query, optional): Page number for results (default: 0).

        • pageSize (query, optional): Number of items per page (default: 10).

        • status (query, optional): Model status, case-sensitive.

        • name (query, optional): Model name, case-sensitive, for substring matching.

      • Returns a list of model objects containing: modelId, modelName and status of the model.

    • /model/{modelId}/activate (POST)

      • Activates a specific custom model, making it available for use.

      • Parameters:

        • modelId: Identifier of the model to activate.

    • /model/{modelId}/deactivate (POST)

      • Deactivates the specified custom model.

      • Parameters:

        • modelId: Identifier of the model to deactivate.

    • /model/{modelId} (DELETE)

      • Deletes the specified custom model permanently.

      • Parameters:

        • modelId: Identifier of the model to delete.

  • /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.

      • Parameters:

        • modelId (body): name/identifier of model.

        • text (body): text to analyze.

      • Returns operationId - analysis identifier.

    • /analyze/initialize/file (POST) - used to initialize text analysis with file. Requires the text file with text to be analyzed and a language model identifier as a parameter. Returns a unique OperationId analysis identifier.

      • Parameters:

        • modelId (body): name/identifier of model.

        • text (body): text to analyze.

      • Returns operationId - analysis identifier.

    • /analyze/{operationId}/status (GET) - returns the status of the text analysis. Requires the OperationId identifier as a parameter.

      • Parameters:

        • operationId (query): analysis identifier.

      • Returns analysis status.

    • /analyze/{operationId}/result (GET) - returns the result of the text analysis (if available). Requires the OperationId identifier as a parameter.

      • Parameters:

        • operationId (query): analysis identifier.

      • Returns analysis result.

  • /algorithm

    • /algorithm/versions (GET) - returns a list of available pre-defined language models.

    • /algorithm/versions/details (GET) - returns detailed descriptions and example use cases of the pre-existing language models.

  • /openapi

    • /openapi (GET) - provides the complete OpenAPI definition of the Smabbler API, including specifications of all available endpoints, request and response formats.

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.

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 /algorithm/versions endpoint.

  • for custom model - use the unique model ID, which can be copied from Manage models list.

Limits and quotas

There are the following limits and quotas for API usage:

  • max 10 requests per second

  • max 100000 requests per month

  • max analyzed text length (sent in the /analyze/initialize request) - 2000000 characters.

API Billing

API usage is based on GCUs, which are consumed while models are active. For full details about GCUs, free trial access and purchasing credits, see the Account & Access section.

Previousvia Open-ParseNextTypical API use

Last updated