​
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/ and sign in to your account or email us to 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

[
  {
    "label": "GPT-3.5",
    "value": "gpt-3.5"
  },
  {
    "label": "GPT4o",
    "value": "gpt4o"
  }
]

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

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.

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

Start a 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

{
  "conversation_id": "<string>",
  "title": "<string>",
  "messages": {
    "id": "<string>",
    "text": "<string>",
    "redacted": "<string>",
    "synthetic": "<string>",
    "ner_count": 123,
    "response": "<string>",
    "ner_items": [],
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Step 2: Send a Message in the Conversation

Send a Message

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

{
  "conversation_id": "<string>",
  "sender": "ai | sender",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "model": "gpt-4o",
  "related_questions": ["<string>"],
  "id": "<string>",
  "typing_completed": true,
  "created_at": "2023-11-07T05:31:56Z"
}

​
Step 3: Continue the Conversation

Continue a 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

{
  "conversation_id": "d0c73687-cc8d-4628-be2d-01050d32dfb6",
  "sender": "user",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "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"
}