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

# REST API

## Base URL

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

## Authentication

```
Authorization: Bearer ndb_live_your_api_key_here
```

## Query Endpoint

```http
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:

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

## Document Endpoints

### Insert

```http
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

```http
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 |