Adding a trusted document to your Locusive account

Locusive's API acts as an alternative to a vector database, letting you add (and query) documents to your account. By adding these documents, any queries you make, either via our chatbots or our API, will automatically look up the most relevant portions of your documents for a given query and use those portions to find the answer to your question.

The Add Document API endpoint allows you to add a document (by URL) or document snippet (by directly providing the text of the document) to your account.

Endpoint

POST <[<https://api.locusive.com/v1/documents>](https://api.locusive.com/v1/documents)>

Request Headers

The API request must include the following header:

Authorization: Bearer <Your-Secret-Key> - The secret key for authenticating the API request.

Request Body Parameters

name (string, required): The name of the document or document snippet that you'd like to add
description (string): A description of the document or document snippet
uri (string, this or text is required): A URI for the document, if provided, the contents of your document will be updated monthly in our systems
text (string, this or uri is required): The text that should be added as a trusted source of information

Example Java code

package com.locusive.public_api.ad_hoc;

import com.google.gson.Gson;
import com.locusive.public_api.PublicApiConfig;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import java.util.HashMap;
import java.util.Map;

public class AdHocIndexTextContentViaPublicApiScript {
	private static final String ApiKey = "your-api-key";
	private static final String Url = "https://api.locusive.com/v1/documents";

	public static void main(String[] args) {
		try {
			HttpPost httpPost = new HttpPost(Url);
			httpPost.addHeader("Authorization", "Bearer " + ApiKey);
			httpPost.addHeader("Content-Type", "application/json"); // indicate we're sending JSON

			// Construct the request body
			Map<String, Object> requestBody = new HashMap<>();
			requestBody.put("name", "Facebook");
			requestBody.put("description", "This short snippet contains a description of the software company Facebook");
			requestBody.put("uri", "https://en.wikipedia.org/wiki/Facebook");
			/* Alternatively, you could pass in some text as below
			requestBody.put("text", "Facebook is a social media platform");
			*/

			String jsonBody = new Gson().toJson(requestBody);
			httpPost.setEntity(new StringEntity(jsonBody));

			// Execute the HTTP request
			try (CloseableHttpClient httpClient = HttpClients.createDefault();
			     CloseableHttpResponse response = httpClient.execute(httpPost)) {

				HttpEntity entity = response.getEntity();
				if (entity != null) {
					String result = EntityUtils.toString(entity);
					System.out.println("Results:");
					System.out.println(result);
				}
			}
		} catch (Exception ex) {
			ex.printStackTrace();
		}
	}
}

Responses

201: Returns the ID of the newly created document
400: A bad request error
403: Permission denied error
500: If there is an internal server error while processing the request

Example Response

{
  "76171517-a097-489f-995c-c15bcce77fb8"
}