Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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 along with additional details: the original file name (fileName), file size in bytes (size), creation timestamp (createDate), last modification timestamp (modifiedAt), analysis efficiency score (efficiency), associated tags (tags), and the size of generated graph load items in bytes after analysis (graphLoadSize). 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 after 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: 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

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?"

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:

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:

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.

Agent Conversation

Initialize Conversation

To begin a new agent conversation with the Smabbler API, you must first initialize a query.

This is a POST request that accepts a JSON body with the following parameters:

  • question - the primary question you want the agent to answer.

  • subqueries - available values:

    • OriginalQuery

    • TwoSubqueries

    • ThreeSubqueries

  • modelsIds - a list of model identifiers the agent should use to find the answer.

The response provides an operationId, which can be used to track the conversation status and retrieve results.

Check Conversation Status

After initializing a conversation, you should monitor its progress.

Request Details

  • Endpoint: /agent/conversation/{operationId}/status

  • Method: GET

The response contains:

  • operationId - the unique identifier of the conversation operation.

  • status - e.g. processed, failed.

  • message - a descriptive status message.

Once the status is processed, you can fetch the results.

Fetch Conversation Results

When the conversation status is processed, you can retrieve the agent's answer.

Request Details

  • Endpoint: /agent/conversation/{operationId}/result

  • Method: GET

Each response contains the following fields:

  • operationId - the unique identifier of the conversation operation.

  • status - the current processing status of the conversation (e.g. processed, failed, pending).

  • message - a descriptive message indicating the current state of the conversation.

  • answer - the final answer generated by the agent. The answer is returned as a Markdown-formatted string and may contain headings, lists, tables or other Markdown elements.

Fetch Detailed Conversation Results

If you need to inspect how the agent arrived at its answer, you can retrieve a detailed conversation result.

Request Details

  • Endpoint: /agent/conversation/{operationId}/result/detailed

  • Method: GET

The response provides a comprehensive payload containing the final conversation result together with additional debugging and processing metadata. Besides the generated answer, it includes subqueries created by the agent, shard execution details and intermediate processing results used during conversation analysis.

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.

Editing Model Sources

If you need to update the data your model is based on, you can add or remove source files without rebuilding the model from scratch. To do this, use the PATCH method on the /model/{modelId}/sources endpoint.

  • Endpoint: /model/{modelId}/sources

  • Method: PATCH

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

The request body must contain at least one of the following lists:

  • add: A list of sourceId values to attach to the model. Each source must have the Analyzed status.

  • remove: A list of sourceId values to detach from the model.

Both lists can be provided at the same time, making the operation atomic - a source swap happens in a single request.

Expected Response

Upon a successful request, the API will return a 200 OK status code along with the updated model details: modelId, modelName, and status. If the model was active at the time of the request, its provisioning state will change to Updating as the model incorporates the new source set.

Sources not currently assigned to the model are silently ignored when listed in remove, making the operation safe to retry.

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, including pagination metadata (totalCount, page, pageSize). Each source item contains the same fields as the single source response: sourceId, status, fileName, size, createDate, modifiedAt, efficiency, tags and graphLoadSize.

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, including pagination metadata (totalCount, page, pageSize). Each model item contains: modelId, modelName, status, and modifiedDate.

Account & GCU balance

Smabbler API usage is metered in GCUs, which are consumed while your models are active. You can check your remaining balance at any time with a single call to /account/gcu.

Check remaining GCUs

  • Endpoint: /account/gcu

  • Method: GET

  • Headers: x-api-key (required) - your API key.

  • Parameters: none. The account is resolved from your API key.

The response returns the amount of GCUs you still have available.

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

PreviousAPI guideNextSDKs

Last updated