mdcms/neuraldb-docs/pages/sdk-rest.md

title	sort	section-id	keywords	description	language
REST API	130	client-sdks	REST API, HTTP, endpoints, authentication, JSON, API	NeuralDB REST API reference — all endpoints, authentication headers, and response formats	en

REST API

Base URL

https://your-neuraldb-host:8080/api/v1

Authentication

Authorization: Bearer ndb_live_your_api_key_here

Query Endpoint

POST /api/v1/query
Content-Type: application/json
Authorization: Bearer ndb_live_...

{
  "query": "SELECT id, content, 1 - (embedding <=> $1) AS similarity FROM documents ORDER BY embedding <=> $1 LIMIT 5",
  "params": [[0.023, -0.187, 0.412]],
  "database": "mydb"
}

Response:

{
  "rows": [{"id": "uuid-1", "content": "First document", "similarity": 0.923}],
  "rowCount": 1,
  "executionTimeMs": 3.2
}

Document Endpoints

Insert

POST /api/v1/collections/my_docs/documents

{"documents": [{"content": "NeuralDB is an AI-native database", "metadata": {"source": "blog"}}],
 "embedding_model": "openai/text-embedding-3-small"}

Search

POST /api/v1/collections/my_docs/search

{"query": "AI-native database", "limit": 10, "min_similarity": 0.7,
 "filters": {"category": "technology"}, "embedding_model": "openai/text-embedding-3-small"}

Error Codes

HTTP Status	Error Code	Description
400	QUERY_ERROR	Invalid NQL query
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Insufficient role permissions
404	NOT_FOUND	Document or collection not found
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error

Rate Limits

Plan	Queries/min	Documents/min
Starter	30	100
Developer	300	1,000
Business	3,000	10,000