Skip to main content

Creating and Managing Bots via API

This documentation describes API methods for creating and managing search (RAG) bots. For example, you can check bot status, view their list, or add/remove documents. The full list of available methods is described below.

Creation with File Upload​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F "files=@/path/to/test.pdf" \
     -F "files=@/path/to/test2.pdf" \
     -F "user_story=write_your_user_story_here" \
     -F "sync=1" \
     -F "time_to_eval=2025-04-02 14:49"

Parameters:

  • YOUR_TOKEN_HERE - token for API access
  • bot_id - index name by which the created bot will be accessible
  • user_story - brief description of the use case (user story)
  • sync (optional) - indexing priority flag (1 - high priority, indexing will be performed before bot creation requests without the flag and before any documents added to existing bots)
  • time_to_eval (optional) - time after which indexing will begin (format: YYYY-MM-DD HH:MM)
info

The sync and time_to_eval parameters can be specified simultaneously.

note

This method has a user_story parameter, which is a description of the assistant's use case. The user story directly affects the quality of indexing and subsequent assistant responses.

When writing a user story, it's recommended to answer the questions: Who will use the assistant and why? What's important when forming a response?

User Story Examples:​

Example 1: "As an engineer in the corporate project department, I want to find out how to act in a complex work situation. After describing a work situation, I want to receive instructions on what to do and who to contact. It's important for me to get people's contacts. It's important to get explanations of what can and cannot be done. I don't like general answers - I've been with the company for a long time and know the general points."

Example 2: "As an employee of an organization who works with various corporate IT systems, I want to find out the information I need about working with one of the systems, get help with my question, and learn how to act in a specific situation. After asking a question, I want to see a short and comprehensive answer containing all the necessary information. Distortion of facts is the most serious problem for me. Depending on the question, incomplete presentation of facts can also be a problem."

Responses:​

  • 202 Accepted – bot creation command accepted for processing. The response will contain command_id. 
    {
      "command_id": "some-unique-command-id"
    }

To track execution status, use the command status endpoints (see the "Tracking Command Statuses" section).

Creation with File URLs​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "direct_link", "url": "https://example.com/doc1.pdf"}' \
     -F "user_story=write_your_user_story_here" \
     -F "sync=1" \
     -F "time_to_eval=2025-04-02 14:49"

Parameters are similar to the file upload request, except:

Responses:​

  • 202 Accepted – bot creation command with URL specified accepted for processing. The response will contain command_id. 
    {
      "command_id": "some-unique-command-id"
    }

To track execution status, use the command status endpoints.

Bot Deletion​

Deleting a bot by its identifier.

curl -X DELETE https://bot.insightstream.ru/indexapi/bot/bot_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

Description​

Allows initiating deletion of a bot and its indexed data. The operation is asynchronous.

Parameters​

  • bot_id (string, path) – bot identifier.

Headers​

  • Authorization: Bearer YOUR_TOKEN_HERE – API access token.

Responses​

  • 202 Accepted – bot deletion command accepted for processing. The response will contain command_id.

    {
      "command_id": "some-unique-command-id"
    }

    To track execution status, use the command status endpoints.

  • 404 Not Found – bot not found.

  • 409 Conflict – bot is in the process of executing another critical operation (e.g., deletion already started), try again later.

Getting Information About Existing Bots

Specific Bot​

To get information about a specific bot, use the following request:

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

This endpoint returns detailed information about the bot, including its settings and file list.

Example response:

{
  "name": "bot_id",
  "hello_text": "\n<h1>Nice to meet you!</h1>\n<h1>I'm your personal AI assistant.</h1>\n<p>I've been trained to answer questions about your documents.</p>\n",
  "retrive_n": 5,
  "support_n": 3,
  "example_questions": [],
  "user_story": "test",
  "bot_creator_credentials": "qwe",
  "files": [
    "http://is.local/documents/bot_id/bob.txt",
    "http://is.local/documents/bot_id/alice.txt"
  ]
}

All Bots​

curl -X GET https://bot.insightstream.ru/indexapi/bots -H "Authorization: Bearer YOUR_TOKEN_HERE"

This endpoint provides detailed information about all bots.

Example response:

{
  "bot_id_1": {
    "name": "bot_id_1",
    "hello_text": "\n<h1>Nice to meet you!</h1>\n<h1>I'm your personal AI assistant.</h1>\n<p>I've been trained to answer questions about your documents.</p>\n",
    "retrive_n": 5,
    "support_n": 3,
    "example_questions": [],
    "user_story": "test",
    "bot_creator_credentials": "qwe",
    "files": [
      "http://is.local/documents/snark.txt",
      "http://is.local/documents/alice.txt"
    ]
  },
  "bot_id_2": {
    // Similar information for other bots
  }
}

Working with Documents Within a Bot

Adding or Updating a Document in a Bot​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/document \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F "file=@/path/to/document.pdf" \

Description​

Allows initiating addition of a new document or updating an existing one in the bot's index.

Parameters​

  • bot_id (string, path) – bot identifier.
  • file (file, form) – document file.

Headers​

  • Authorization: Bearer YOUR_TOKEN_HERE – API access token.

Responses​

  • 202 Accepted – document add/update command accepted. The response will contain command_id.

    {
      "command_id": "some-unique-command-id-for-doc-upsert"
    }

    To track execution status, use the command status endpoints.

  • 404 Not Found – bot not found.

  • 409 Conflict – bot or this document is being processed by another command, try again later.

Adding or Updating a Document in a Bot by URL​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/document_by_url
-H "Authorization: Bearer YOUR_TOKEN_HERE"
-F "url=https://example.com/doc1.pdf" \

Description​

Allows initiating addition of a new document or updating an existing one in the bot's index by URL.

Parameters​

  • bot_id (string, path) – bot identifier.
  • url (file, form) – direct link to the document.

Headers​

  • Authorization: Bearer YOUR_TOKEN_HERE – API access token.

Deleting a Document from a Bot​

curl -X DELETE https://bot.insightstream.ru/indexapi/bot/bot_id/document/doc_name -H "Authorization: Bearer YOUR_TOKEN_HERE"

Description​

Initiates deletion of the specified document from the bot's index. The operation is asynchronous.

Parameters​

  • bot_id (string, path) – bot identifier.
  • doc_name (string, path) – document name.

Headers​

  • Authorization: Bearer YOUR_TOKEN_HERE – API access token.

Responses​

  • 202 Accepted – document deletion command accepted. The response will contain command_id.

    {
      "command_id": "some-unique-command-id-for-doc-delete"
    }

    To track execution status, use the command status endpoints.

  • 404 Not Found – bot or document not found.

  • 409 Conflict – bot or document is being processed by another command, try again later.

Tracking Operation Statuses

Operations for creating/deleting a bot (assistant) or adding/deleting documents are asynchronous. Upon successful acceptance of the request, the API returns command_id. It's preferable to use this universal identifier to track the execution status of the command.

Getting Status of All Operations for a Bot​

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id/commands -H "Authorization: Bearer YOUR_TOKEN_HERE"

Returns a list of JSON objects with descriptions of all active or recently completed commands for the specified bot_id.

Example Response:​

{
  "command_id_1": {
    "status": "processing",
    "progress": {
      "documents": { 
        "total": 98, 
        "complete": 76 
      },
      "current_document": { 
        "total": 54, 
        "complete": 32 
      }
    }
  },
  "command_id_2": {
    "status": "complete"
  }
}

Response Field Descriptions:​

  • command_id: Unique command identifier
  • status: Current command status (possible values: "processing", "complete", etc.)
  • progress: Information about command execution progress (present only for bot indexing or new documents in progress)
    • documents: Progress of processing at the document level in the bot
      • total: Total number of documents to process
      • complete: Number of documents already processed
    • current_document: Progress of processing at the single document level
      • total: Total number of chunks in the current document
      • complete: Number of chunks already processed in the current document

Getting Status of a Specific Command​

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id/command/your_command_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

Where your_command_id is the command identifier received when it was initiated.

Response Format: JSON object containing the following fields:

  • status (string): Current command status. Possible values:
    • pending: Command is waiting to start execution.
    • processing: Command is in progress.
    • complete: Command completed successfully.
    • error: An error occurred during command execution.
    • canceled: Command was canceled.

Important Note on complete, error, canceled Statuses: The complete, error, canceled statuses are shown only once, after which the status is considered viewed and further requests for this command's status may return {"error": "not found"}

Other Status Tracking Tools

Checking Status of All Bot Documents​

curl https://bot.insightstream.ru/indexapi/bot/bot_id/documents -H "Authorization: Bearer YOUR_TOKEN_HERE"

Description​

Returns statuses of all documents loaded into the bot.

Parameters​

  • index_id (string, path) – bot identifier.

Responses​

  • 200 OK – list of statuses successfully retrieved.
  • 404 Not Found – bot not found or bot has no loaded documents.

Checking Document Status​

curl https://bot.insightstream.ru/indexapi/bot/bot_id/document/doc_name -H "Authorization: Bearer YOUR_TOKEN_HERE"

Description​

Returns the current processing status of a document in the bot.

Parameters​

  • index_id (string, path) – bot identifier.
  • doc_name (string, path) – document name.

Responses​

  • 200 OK – status successfully retrieved.
  • 404 Not Found – bot or document not found.
  • 409 Conflict – error processing document.