> For the complete documentation index, see [llms.txt](https://smabbler.gitbook.io/smabbler/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smabbler.gitbook.io/smabbler/api/api-guide.md).
# 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 your custom built model.
* There are certain API limits and quotas.
***
## API endpoints
The Smabbler API has 23 endpoints divided into 6 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. Maximum file size is 400 MB.
* A response containing a unique identifier of the source: `sourceId`.
* **/source/{sourceId} (GET)**
* Retrieves details for a specific source.
* *Parameters*:
* `sourceId`: The unique identifier of the source to retrieve.
* Returns source details: `sourceId`, `status`, `fileName`, `size` (in bytes), `createDate`, `modifiedAt`, `efficiency` , `tags` and `graphLoadSize`.
* **/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 paginated list of source objects. Each item contains: `sourceId`, `status`, `fileName`, `size` (in bytes), `createDate`, `modifiedAt`, `efficiency`, `tags` and `graphLoadSize`. Pagination metadata: `totalCount`, `page`, `pageSize.`
* **/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.
* *Parameters*:
* `modelId`: Unique identifier of the model to retrieve.
* Returns model details: `modelId`, `modelName`, `status`, `modifiedDate`, a `history` array (each entry contains `date` and `description` of a status change), and a `sources` array (each entry contains `sourceId` and `fileName` of a source currently attached to the model).
* **/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 paginated list of model objects. Each item contains: `modelId`, `modelName`, `status`, and `modifiedDate`. Pagination metadata: `totalCount`, `page`, `pageSize`.
* **/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}/sources (PATCH)**
* Adds or removes sources from a specific custom model.
* *Parameters*:
* `modelId` (route): Unique identifier of the model to update.
* `add` (body): List of source identifiers to add to the model.
* `remove` (body): List of source identifiers to remove from the model.
* At least one of `add` or `remove` must be non-empty.
* Returns updated model details: `modelId`, `modelName` and `status`.
* **/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, max length: 2,000,000 characters.
* 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.
* **/analyze/sharded/initialize (POST)** - used to initialize a sharded text analysis across multiple models simultaneously. This allows for parallel processing and result aggregation from different models. Returns a unique OperationId identifier.
* *Parameters*:
* `modelsIds` (body): list of model identifiers (e.g., \["id1", "id2"]).
* `text` (body): text to analyze, max length: 2,000,000 characters.
* **/agent/conversation**
* **/agent/conversation/initialize (POST)** - initializes a new agent conversation operation. Returns a unique `OperationId` identifier.
* *Parameters:*
* `question` (body): the primary question to be addressed by the agent.
* `subqueries` (body): number of subqueries represented as a word. **OriginalQuery** = no subqueries, only original question will be used; **TwoSubqueries** and **ThreeSubqueries** represent respective number of 2 or 3 subqueries sent to Smabbler models.
* `modelsIds` (body): list of model identifiers to be used for the conversation.
* Returns `operationId` - conversation identifier.
* **/agent/conversation/{operationId}/status (GET)** - retrieves the current status of the conversation operation.
* *Parameters:*
* `operationId`: unique identifier of the conversation operation.
* Returns conversation status and an associated message.
* **/agent/conversation/{operationId}/result (GET)** - returns the high-level result of the conversation analysis.
* *Parameters:*
* `operationId`: unique identifier of the conversation operation.
* Returns conversation result data.
* **/agent/conversation/{operationId}/result/detailed (GET)** - provides a comprehensive and detailed result of the conversation, including underlying analysis steps.
* *Parameters:*
* `operationId`: unique identifier of the conversation operation.
* Returns detailed conversation results and metadata.
* **/openapi**
* **/openapi (GET)** - provides the complete OpenAPI definition of the Smabbler API, including specifications of all available endpoints, request and response formats.
* **/account**
* **/account/gcu (GET)** - returns the number of GCUs still available for the account associated with the request's API key. GCUs are consumed while models are active. Use this endpoint to check how much of your balance is left.
* *Parameters*:
* This endpoint takes no query, path or body parameters. The account is resolved from the **x-api-key** header.
* Returns:
* `remainingGcus` (number): the amount of GCUs currently available for the account. Returned as a floating-point value (e.g. `1250.0`).
* Possible responses:\
`200 OK` - GCU information retrieved successfully.\
`404 Not Found` - no active subscription found for the account (`"No active subscription found"`).\
`500 Internal Server Error` - `"Cannot retrieve GCU information for the account"`.
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. To find it, click your username in the bottom-left, then select **Account**.
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** page.
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** page (click your username in the bottom-left, then select **Account**). 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** page, 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.
***
## 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](/smabbler/smabbler-portal/account-and-access.md) section.