Send A Chat Message

This example shows you how to send a chat message

Sending a contextual chat message

The Send Chat Message API endpoint allows you to send a chat message to a large language model while including any relevant context or integrated tools that you've added to your account.



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

  • chatMessages (array of strings, required): A list of chat messages (or a single chat message if you do not want to provide historical context to be used in the query).
    • A chatMessage has two attributes: role (required, either "user" or "assistant") and message (required)
  • systemPrompt (string): The system prompt you'd like to use when sending a message

Example Java code

package com.locusive.public_api.ad_hoc;

import com.locusive.public_api.PublicApiConfig;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AdHocChatMessageSenderViaPublicApi {
	private static final String ApiKey = "your-api-key";
	private static final String Url = "";

	public static void main(String[] args) {
		HttpClient httpClient = HttpClients.createDefault();
		Gson gson = new Gson();

		List<Map<String, String>> chatMessages = new ArrayList<>();
		chatMessages.add(createMessage("user", "Hello there!"));
		chatMessages.add(createMessage("assistant", "Hello! How can I assist you today?"));
		chatMessages.add(createMessage("user", "What's the weather in NYC tomorrow?"));

		Map<String, Object> requestBody = new HashMap<>();
		requestBody.put("chatMessages", chatMessages);

		try {
			HttpPost postRequest = new HttpPost(UrlBase);
			StringEntity entity = new StringEntity(gson.toJson(requestBody));
			postRequest.setHeader("Content-Type", "application/json");
			postRequest.addHeader("Authorization", "Bearer " + ApiKey);

			HttpResponse response = httpClient.execute(postRequest);
			String responseBody = EntityUtils.toString(response.getEntity());

			System.out.println("Response Code: " + response.getStatusLine().getStatusCode());
			System.out.println("Response Body: " + responseBody);

		} catch (Exception e) {

	private static Map<String, String> createMessage(String role, String message) {
		Map<String, String> msg = new HashMap<>();
		msg.put("role", role);
		msg.put("message", message);
		return msg;


  • 200: The response from the large language model
  • 400: A bad request error
  • 500: If there is an internal server error while processing the request

Example Response

  "The weather in NYC tomorrow is partly cloudy with a high of 83°F and a low of 72°F. There is a 24% chance of rain, and the wind will be from the west-northwest at 6 mph.
Sources: The Weather Channel ("