Add A Trusted Document

This example shows you how to add an example document

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.


POST <[<>](>

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.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 = "";

	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", "");
			/* 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);
		} catch (Exception ex) {


  • 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