Typical API use

In this section, you will find a typical Smabbler API use example. Based on our own file sources, we will create a custom model and then analyze the text using this model. After everything is done, we will clean up the created resources.

Prerequisites

To use the API you will need:

• an active API key (see more about the API key here). The key value must be sent in every request in x-api-key header value.

• a REST API / HTTP client. For example purposes, we will use Scalar embedded in the Smabbler Portal, but you can use any other client like Postman, Insomnia, curl, etc.

---

For the purpose of this example, the API client used is Scalar, which is embedded in the Smabbler Portal and can be accessed from the Home page under Useful links → API definition.

Source

Uploading Source Files

To begin, we'll upload the source files that will be used to train our custom model. We'll use the POST method on the /source/file endpoint.

Request Details

• Endpoint: /source/file

• Method: POST

• Content-Type: multipart/form-data

We will be uploading two files:

1. A CSV file: This file contains 100 entries with film information, including id and movie description. You can find this file in the Test datasets section of the documentation.

2. A TXT file: This file contains a description of a single movie that is not present in the CSV file.

The current file size limit is 400 MB.

Expected Response

Upon a successful upload, the server should return a 200 OK status code. The response body will contain a sourceId, which is a unique identifier for the uploaded source. We will need to save this sourceId to use in subsequent steps of our workflow.

CSV file

TXT file

---

Checking Source Status

At any point, you can check the status of an uploaded source using its unique identifier. This is useful for monitoring the processing of your files before they are used for model creation.

To perform this check, use the GET method on the /source/{sourceId} endpoint.

Request Details

• Endpoint: /source/{sourceId}

• Method: GET

The {sourceId} parameter in the URL must be replaced with the identifier you received after the successful file upload.

Expected Response

A successful request will return the current status of the source. This allows you to track the progress and ensures that your data is prepared before moving on to the next step.

For example, here's a status check of the CSV file immediately after its upload:

---

Analyzing the Source

Before any source can be used, it must be analyzed. The analysis process differs slightly depending on the file type.

Analyzing a TXT File

This is the more straightforward process. You'll use the POST method on the /source/{sourceId}/analyze/txt endpoint.

• Endpoint: /source/{sourceId}/analyze/txt

• Method: POST

• Path Parameter: {sourceId} must be the identifier for your uploaded TXT file.

The expected response is a 200 OK status code upon successful analysis.

Analyzing a CSV File

The process for a CSV file is similar but requires additional parameters in the request body. You'll use the POST method on the /source/{sourceId}/analyze/csv endpoint.

• Endpoint: /source/{sourceId}/analyze/csv

• Method: POST

• Path Parameter: {sourceId} must be the identifier for your uploaded CSV file.

Additionally, the request body must contain the following JSON object:

JSON

{
  "idColumnName": "id",
  "textColumnNames": [
    "movie description"
  ]
}

• idColumnName: Specifies the column containing the identifier. In our case, it's id.

• textColumnNames: A list of columns that hold the text data to be analyzed. For our file, this is the movie description column.

A successful response will again return a 200 OK status code.

Source analysis can take a while, depending on the amount of information in the input files.

Checking Source Post-Analysis Status

After initiating the analysis of your source files, you can check their status to ensure the process is complete. This is the same endpoint you used before.

For example, here's the status of our CSV file after the analysis has been completed:

---

Model

Building the Model

Once your sources have been successfully analyzed, the next step is to build a new custom model using that data. To do this, we'll use the POST method on the /model/build endpoint.

Request Details

• Endpoint: /model/build

• Method: POST

The request body needs to specify the modelName and a list of sources (the sourceId values) to be included in the model.

For our example, we will create a model named "101 movies" using both the TXT and CSV source files we previously uploaded and analyzed. The body will look like this:

JSON

{
  "modelName": "101 movies",
  "sources": [
    "a04fd537-16ef-473b-b02f-16f8fe512ca8",
    "37d0513f-c5b3-419f-9adf-446e3ca1e707"
  ]
}

The sources array should contain the sourceId for each of your analyzed files.

Expected Response

Upon a successful request, the API will return a JSON object containing the modelId—a unique identifier for your new model—and its initial status. You will need to store this modelId for future interactions with the model.

The same sources can be used to create multiple models.

---

Checking Model Status

Similar to how you checked the status of your source files, you can monitor the status of your newly created model at any time. This allows you to track its build progress.

To do this, use the GET method on the /model/{modelId} endpoint.

Request Details

• Endpoint: /model/{modelId}

• Method: GET

• Path Parameter: {modelId} should be the unique identifier you received after building the model.

The response will contain the current status of the model, which will inform you if it's still being built or is ready for next step.

---

Activating the Model

Once your model has been successfully built, the final step is to activate it. You should only activate a model when you're prepared to use it, as this process allocates additional system resources.

To activate the model, use the POST method on the /model/{modelId}/activate endpoint.

Request Details

• Endpoint: /model/{modelId}/activate

• Method: POST

• Path Parameter: {modelId} should be the unique identifier of the model you built in the previous step.

Expected Response

Upon an activation request, the API will return a 200 OK status code and the initial status of the activation operation.

Model activation can be a time-consuming operation, depending on the size of your source data.

You can check the status using the previously mentioned endpoint while waiting for the model to become active.

When a model is active, it becomes ready for use. At this point, you can perform queries on it, a process we will refer to as analysis.

---

Analysis

Initialize Analysis

To begin a new analysis with the Smabbler API, you must first initialize a query. This is a POST request that accepts a JSON body with the following parameters:

• modelId: The model identifier used for the analysis. In our case, this will be the modelId built in the previous steps.

• text: The text you want to analyze.

For our example, we will use the question: "In which movies did Tom Hanks act?"

{
  "modelId": "c0c455f8-0f25-412e-a1c4-392ea3ecc4d3",
  "text": "In which movies did Tom Hanks act?"
}

The response to this request will provide an operationId. This unique identifier allows you to query the API for the status and final result of your analysis.

Be aware that query processing can take some time, depending on the model's complexity, the size of your query, and the system's load. It's recommended to periodically check the status of your operation, as described in the next step.

The current text limit is 2,000,000 characters.

---

Check Analysis Status

After initializing an analysis, you can check its current status. This is necessary to confirm that the operation has been completed and the results are ready to be retrieved.

Request Details

• Endpoint: /analyze/{operationId}/status

• Method: GET

The request query must contain the operationId you received from the /analysis/initialize request response, in our case it will look like these:

/analyze/c0c455f8-0f25-412e-a1c4-392ea3ecc4d3/status

Expected Response

The response will contain the status field. You should observe this field to track the analysis progress. If the status is processed, you can proceed to acquire the final results. You can find more information about all possible analysis statuses in the Analysis statuses docs.

---

Fetch Analysis Results

Once the analysis has been completed and the status is processed, you can fetch the final results. This step requires the operationId you obtained from the /analysis/initialize request.

Request Details

• Endpoint: /analyze/{operationId}/result

• Method: GET

The request query must contain the operationId of the completed analysis, in our case:

/analyze/c0c455f8-0f25-412e-a1c4-392ea3ecc4d3/result

Expected Response

The analysis results can be found in the result field within the JSON response body.

Additional details on the NLP parsing can be found at the URL provided in the nlpParsingUrl field of the response.

It's important to note that this is a short-lived link that will expire after a certain period. If the link becomes unavailable, you must make a new request to fetch the results again to generate a fresh, valid URL.

The analysis results are also available for a limited time. After this period expires (typically 24 hours), you will need to re-run the analysis to get results.

---

Sharded Analysis

You can also send a query to several models simultaneously, allowing you to obtain combined results from each of them.

Let's assume you have two models with the IDs "969c4978-4293-4a35-a32f-c2295ef7e247" (model1) and "493e49bd-b7b4-4cb2-a6e9-f3efeb30ff43" (model2). You submit your query by providing the model IDs as a list. In response - similar to a regular analysis - you receive an operation ID.

Using this ID, you can poll the regular Results endpoint, which in this case will return a slightly different response format containing the results obtained from both queried models.

This is particularly useful if you want to isolate different models or if it is not possible to create a single model that is large enough.

---

Resource Management and Cleanup

After you have finished working with a model, you have several tools at your disposal to manage and clean up resources. This includes deactivating and deleting models, as well as removing the source files used to create them.

Deactivating a Model

Before a model can be deleted, it must first be deactivated. To perform this action, use the POST method on the /model/{modelId}/deactivate endpoint.

• Endpoint: /model/{modelId}/deactivate

• Method: POST

• Path Parameter: {modelId} should be the unique identifier of the model you want to deactivate.

The response will contain the updated status of the model after the deactivation.

---

Deleting a Model

Once a model has been deactivated, you can delete it. This is done using the DELETE method on the /model/{modelId} endpoint.

• Endpoint: /model/{modelId}

• Method: DELETE

• Path Parameter: {modelId} should be the unique identifier of the model you want to remove.

The expected response is a 200 OK status code.

If you were to check the status of the deleted model afterward, the expected status would be Removed.

---

Deleting a Source

Sources can be deleted at any time, as there are no prerequisites like with models. To delete a source, use the DELETE method on the /source/{sourceId} endpoint.

• Endpoint: /source/{sourceId}

• Method: DELETE

• Path Parameter: {sourceId} should be the unique identifier of the source you want to remove.

The expected response is a 200 OK status code.

If you were to try and check the status of the source you just deleted, the API would return a 404 Not Found status code.

---

Listing Resources

To help manage your resources, two endpoints are available for listing your existing sources and models.

Listing Sources

To list the sources you've created, use the GET method on the /sources endpoint. It supports optional pagination parameters:

• Endpoint: /sources

• Method: GET

• Parameters:

  • pageSize: An optional positive integer no greater than 50. The default value is 10.

  • pageNumber: An optional integer starting from zero. The default value is 0 (the first page).

  • status: An optional string, case-sensitive.

• Example:

  • /sources?pagesize=5&page=0&status=Analyzed

The response will return a paginated list of the sources you have created.

---

Listing Models

Similarly, to list your custom models, use the GET method on the /models endpoint. This also supports the same optional pagination parameters:

• Endpoint: /models

• Method: GET

• Parameters:

  • pageSize: An optional positive integer no greater than 50. The default value is 10.

  • pageNumber: An optional integer starting from zero. The default value is 0 (the first page).

  • status: An optional string, case-sensitive.

  • name: An optional string, case-sensitive.

• Example:

  • /models?pagesize=50&page=0&status=Active&name=Movies

The response will return a paginated list of the models you have created.

---

For more information on each endpoint, see the 'API Guide' tab.