Public API | Neural Hiive®

Overview

The Neural Hiive® Public API gives developers programmatic access to the Neural Hiive platform. It accepts natural-language questions and returns a generated answer, source references, citation metadata, assistant metadata, a session ID, and a message ID.

Example environment: http://<your-base-url>. Replace this with your assigned Neural Hiive base URL before deploying to production.

What the API does

Accepts a user question through POST /v1/chat.
Returns a JSON object containing the generated answer, source references, citation metadata, assistant metadata, a session ID, and a message ID.
Can reuse a session_id so later messages continue the same conversation.
Can accept optional extracted document text, image inputs, web search settings, and integration metadata.

Base URL & Endpoints

All API requests are made over HTTPS to your assigned Neural Hiive base URL. The two available endpoints are listed below.

Endpoint	Method	Purpose
`/health`	GET	Check whether the API is available. Expected response: `{"status":"ok"}`.
`/v1/chat`	POST	Send a chat message and receive the complete assistant answer after processing finishes.

Authentication

Every request must include an API key and the assigned username. The username is provided by Neural Hiive for each developer or integration; it is not a global fixed value.

Security requirement: Keep the API key on your server. Never put it in browser JavaScript, mobile applications, public repositories, logs, analytics events, or client-visible configuration.

Recommended headers

HTTP

X-API-Key: <your-api-key>
Content-Type: application/json

Bearer authentication (also supported)

HTTP

Authorization: Bearer <your-api-key>

Quick Start Request

This is the smallest useful request to the platform. Replace the username with the value Neural Hiive provides for your developer account or integration.

HTTP Request

POST http://<your-base-url>/v1/chat
X-API-Key: <your-api-key>
Content-Type: application/json

JSON Body

{
  "query": "Generate a table with a list of contracts that are expriring within the next 90 days",
  "username": "your-assigned-username@example.com",
  "assistant_name": "your-assistant-name",
  "session_id": "demo-session-001",
  "web_search": false
}

Request Fields

The request body must be a JSON object. Unexpected fields are rejected; keep your request body limited to fields supported by the API.

Field	Required	Description
`query`	Required	The user's visible question or message.
`username`	Required	The username assigned to the developer or integration. This is not a fixed value. The API key and username must match provisioned access.
`assistant_name`	Required	The supported assistant name provisioned for the integration.
`session_id`	Recommended	A stable conversation ID generated by your application. Reuse it for follow-up messages in the same conversation.
`end_user_id`	Optional	Your application's user ID for the person using the chat.
`client_timezone`	Optional	The user's timezone, such as `America/Chicago`. Useful for time-sensitive answers.
`client_time`	Optional	The user's local timestamp, such as `2026-05-28T10:30:00-05:00`.
`added_context`	Optional	Extra extracted text for this request. Use this for PDF, Word, or other document text after your application extracts it.
`images`	Optional	Image inputs as data URLs, public image URLs, or objects with a `url` field.
`web_search`	Optional	Set `true` only when public web or recent outside information is needed. Defaults to `false`.
`metadata`	Optional	Optional JSON object for your integration metadata. Do not include secrets or unnecessary personal data.

Successful JSON Response

On success, the API returns HTTP 200 with the following JSON body.

JSON Response

{
  "answer": "Response text...",
  "references": [
    {
      "source_id": "source-id",
      "chunk_ids": ["chunk-id"],
      "knowledgeName": "Knowledge source name",
      "displayText": "Display label",
      "filename": "source-file.pdf",
      "filename_or_url": "source-file.pdf",
      "url": null,
      "preview_url": null,
      "doc_type": "file",
      "page_number": 3,
      "citation_count": 1,
      "snippets": []
    }
  ],
  "citations": {
    "version": 2,
    "provider": "visible_markdown",
    "inline_citations": []
  },
  "assistant": {
    "id": "assistant-id",
    "name": "your-assistant-name",
    "title": "Assistant title",
    "llm": "model-name"
  },
  "session_id": "demo-session-001",
  "message_id": "message-id"
}

Using the Response

Each field in the response serves a specific purpose in your UI and data layer.

Response field	How to use it
`answer`	Render this as the assistant's main response. It may contain Markdown-style text and inline source links.
`references`	Show these beside or below the answer so users can inspect the sources used by the assistant.
`citations`	Use this metadata if your UI renders precise inline citations. Otherwise you can still display references.
`assistant`	Useful for diagnostics, audit logs, and showing which assistant/model handled the request.
`session_id`	Store and reuse this value for follow-up messages in the same conversation.
`message_id`	Store this in logs if you need to map a response to your own records or support tickets.

Runnable Python Example

Use server-side code for all API calls. This example reads configuration from environment variables and posts the question to the local API. It uses only the Python standard library, with no third-party dependencies required.

Python

import json
import os
import urllib.request
import uuid

base_url = os.getenv("NH_API_URL", "http://<your-base-url>").rstrip("/")
api_key  = os.environ["NH_API_KEY"]
username = os.environ["NH_USERNAME"]

payload = {
    "query": "Generate a table with a list of contracts that are expriring within the next 90 days",
    "username": username,
    "assistant_name": os.getenv("NH_ASSISTANT_NAME", "your-assistant-name"),
    "session_id": f"my-app-{uuid.uuid4()}",
    "web_search": False,
}

request = urllib.request.Request(
    f"{base_url}/v1/chat",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "X-API-Key": api_key,
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=120) as response:
    result = json.loads(response.read().decode("utf-8"))

print(result["answer"])
print(result["references"])

JavaScript Server Example

Use this from a backend/server environment only; never directly from browser JavaScript, as that would expose your API key.

JavaScript (Node.js)

const response = await fetch(`${process.env.NH_API_URL}/v1/chat`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.NH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Generate a table with a list of contracts that are expriring within the next 90 days",
    username: process.env.NH_USERNAME,
    assistant_name: "your-assistant-name",
    session_id: "demo-session-001",
    web_search: false,
  }),
});

if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(error.detail || `Neural Hiive request failed: ${response.status}`);
}

const result = await response.json();
console.log(result.answer);
console.log(result.references);

Environment Configuration

Store all secrets in environment variables. Never commit API keys or usernames to version control.

.env

NH_API_URL=http://<your-base-url>
NH_API_KEY=<your-api-key>
NH_USERNAME=your-assigned-username@example.com
NH_ASSISTANT_NAME="your-assistant-name"

Application Architecture

A typical production integration keeps Neural Hiive API calls on your server. Your frontend sends user messages to your backend, and your backend calls the Neural Hiive API with the stored API key. The Neural Hiive API is never called directly from the browser.

Step	Your application does this
1. Start chat	Create a new `session_id` and store it with the chat record.
2. Send message	Send `query`, `username`, `assistant_name`, `session_id`, and optional inputs to `/v1/chat`.
3. API returns JSON	Store `answer`, `references`, `citations`, `session_id`, and `message_id`.
4. UI renders response	Show `answer` first. Show references and source labels near the answer.
5. User follows up	Send only the latest `query` and the same `session_id`. Add request-specific context again if needed.

Sessions & Follow-Up Messages

Your application can create any stable session_id. Reusing the same session_id lets the platform continue the conversation without requiring your app to resend the whole chat history.

First request

JSON

{
  "query": "Summarize this policy.",
  "username": "your-assigned-username@example.com",
  "assistant_name": "your-assistant-name",
  "session_id": "customer-42-chat-1001",
  "added_context": "Extracted policy text..."
}

Follow-up request (same session)

JSON

{
  "query": "What references did you use?",
  "username": "your-assigned-username@example.com",
  "assistant_name": "your-assistant-name",
  "session_id": "customer-42-chat-1001"
}

Added Context & Images

The added_context and images fields let you augment requests with external content that supports the user's question.

Use added_context for extracted document text that supports the current question.
Do not send raw PDF or DOCX files as base64 in added_context. Extract text first using your own document processing pipeline.
Use images only when the question depends on a visual input.
Images can be data URLs, public URLs, or objects like {"url":"https://example.com/image.png"}.
Added context and images are request-specific. Send them again on follow-up requests when they are still needed for the current question.

Web Search

Set web_search to true only when a question may require public internet information or recent information outside configured knowledge sources. It is false by default and applies only to the current request.

JSON

{
  "query": "What changed in the latest published guidance?",
  "username": "your-assigned-username@example.com",
  "assistant_name": "your-assistant-name",
  "session_id": "guidance-review-1001",
  "web_search": true
}

Error Handling

Always handle non-2xx responses before parsing the success object. Error bodies use the following shape:

JSON

{
  "detail": "Error message"
}

Status	Meaning	Recommended handling
401	Missing or invalid API key, missing username, or username does not match provisioned access.	Check server configuration. Do not retry repeatedly.
403	Username exists but lacks access to requested knowledge sources, or user cannot be found.	Escalate access provisioning or show an authorization error.
422	Invalid request body.	Fix the request payload. Check required fields and unexpected fields.
429	Rate limit exceeded.	Use the `Retry-After` header and exponential backoff.
500	Neural Hiive service configuration error.	Log `message_id` if present and contact support.
502	Neural Hiive service unavailable or invalid upstream response.	Retry with backoff.
504	Neural Hiive service timed out.	Retry with backoff or ask the user to try again.

Production Checklist

Before going live, verify each item in this list. These are the most common sources of integration issues.

Store the API key in server-side secret storage.
Never expose the API key in client-side code or public repositories.
Generate and persist one session_id per conversation.
Store message_id for supportability and audit trails.
Display references whenever possible so users can inspect sources.
Retry 429, 502, and 504 with backoff. Respect Retry-Afterfor 429.
Do not send secrets, passwords, payment data, or unnecessary personal information in query or metadata.
Validate and limit user-provided added_context and images before forwarding them.
Log request failures without logging API keys or sensitive user content.

Ready to integrate? Reach out to sales@neuralhiive.ai to get your API key, assigned username, and production base URL.