> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Explore the API workflows designed for seamless document uploading, powerful semantic search, and efficient conversation management
## Welcome
Welcome to our Shieldbase AI API documentation site! Our API provides intuitive endpoints to seamlessly upload documents, execute advanced semantic searches, and manage dynamic conversations. Dive into the two primary workflows below to harness these powerful features effectively.
### Authentication
Before you get started, ensure that all your API requests include the following three headers. These headers are mandatory for all requests to authenticate and authorize your access to the system:
* **client-id**: Your unique client identifier.
* **private-key**: A private key to authenticate your API calls.
* **secret**: A secret key that provides an additional layer of security.
To obtain your `client-id`, `private-key`, and `secret`, please visit
[https://app.sbai.cloud/](https://app.sbai.cloud/) and sign in to your
account or email us to [support@shieldbase.ai](mailto:support@shieldbase.ai). Once you have these credentials, you can start making authenticated
requests.
These headers need to be included in every request you send to the API.
***
## Models API
Retrieve available models for tasks like semantic search and conversation management via the `GET /external/models` endpoint. The response delivers an array of models, each with a `label` and `value` for easy reference.
### Endpoint
**GET** `/external/models`
### Headers
Make sure to include the following headers in your request to authenticate:
* **client-id**: Your unique client identifier.
* **private-key**: A private key used for authenticating your API calls.
* **secret**: A secret key that provides additional security for your requests.
### Response
Upon a successful request, the response will include an array of available models, each represented as an object with the following properties:
* **label**: The human-readable name of the model.
* **value**: The model's identifier, used when specifying which model to use.
### Response Example
```json theme={null}
[
{
"label": "GPT-3.5",
"value": "gpt-3.5"
},
{
"label": "GPT4o",
"value": "gpt4o"
}
]
```
***
### Workflow 1: Upload and Semantic Search
This workflow allows you to upload documents and perform a semantic search across the uploaded files. It’s a two-step process: First, you upload your documents, and then you use the semantic search endpoint to retrieve all the relevant contents.
#### Step 1: Upload Documents
Start by uploading one or more documents using our document upload API
endpoint. This is the first step in the process and requires you to send the
files as part of a `multipart/form-data` request. Make sure that you include
all required headers like `client-id`, `private-key`, and `secret`.
To upload a document or a set of documents, use the `PUT /external/upload` endpoint. This allows you to upload files in various formats. You need to include the files as binary data within a form data, and the server will process them enabling semantic search and other features afterwards. Upon successful upload, the server will return a confirmation message.
#### Step 2: Perform a Semantic Search
After uploading documents, you can retrieve them and their content semantically using keywords
or context through our semantic search endpoint. This helps you find documents
based on their content and similarity, making retrieval easier and efficient.
Once your documents have been uploaded, you can use the `POST /external/semantic-search` endpoint to retrieve content based on specified keywords or query. You’ll also be able to narrow down your search by providing a context ID if needed. This endpoint will return the most relevant documents, giving you easy access to the information you need.
***
### Workflow 2: Conversation Management
Our conversation management API enables you to start, continue, and manage conversations programmatically. The conversation flow starts with initiating a new conversation, sending messages to it, and continuing the conversation when needed.
#### Step 1: Start a New Conversation
Begin a new conversation by sending an initial message to the conversation
API. This endpoint will create a new conversation ID that will be used for
tracking the conversation.
To initiate a new conversation, use the `POST /external/start-conversation` endpoint. You’ll need to provide the message you want to start the conversation with. The server will respond with a `conversation_id` and `model` along with the initial conversation details, such as the messages, ner count, and timestamp.
### Example Response for Start Conversation
```json theme={null}
{
"conversation_id": "",
"title": "",
"messages": {
"id": "",
"text": "",
"redacted": "",
"synthetic": "",
"ner_count": 123,
"response": "",
"ner_items": [],
"timestamp": "2023-11-07T05:31:56Z"
}
}
```
#### Step 2: Send a Message in the Conversation
Once the conversation has started, you can send additional messages to
continue the dialogue. This helps in extending the conversation with new
information.
To continue the dialogue, use the `POST /external/send` endpoint. Include the `conversation_id` received from the `start-conversation` endpoint and your new message in the body of the request. This keeps the conversation flow intact, ensuring that each message is properly linked to its conversation.
### Example Response for Send Conversation
```json theme={null}
{
"conversation_id": "",
"sender": "ai | sender",
"message_text": "",
"redacted_text": "",
"syntactic_text": "",
"model": "gpt-4o",
"related_questions": [""],
"id": "",
"typing_completed": true,
"created_at": "2023-11-07T05:31:56Z"
}
```
#### Step 3: Continue the Conversation
Use this endpoint to continue the ongoing conversation by adding new responses
to it. This ensures that the conversation can evolve over time.
If you want to further extend the conversation, you will need to use the `POST /external/continue` endpoint, providing the `conversation_id` and `model` and any additional information required to keep the conversation going. After calling `continue-conversation`, you can return to the `send-conversation` endpoint to send new messages within the same conversation context.
### Example Response for Continue Conversation
```json theme={null}
{
"conversation_id": "d0c73687-cc8d-4628-be2d-01050d32dfb6",
"sender": "user",
"message_text": "",
"redacted_text": "",
"syntactic_text": "",
"typing_completed": true,
"created_at": "2024-08-16T09:24:07.865867",
"ner_items": [],
"ner_count": 123,
"title": "Dropbox: A Popular File Sharing Service",
"id": "ac3ca0a0-69ee-49c3-a6a5-86ee9b9f4c0e"
}
```