# NexusAPI v3 — Complete Developer Reference

Last updated: January 2025 | Version: 3.4.2 | Base URL: `https://api.nexus.io/v3`

## 1. Authentication

NexusAPI uses OAuth 2.0 Bearer tokens for all API calls. Tokens expire after 3600 seconds (1 hour). Refresh tokens are valid for 30 days. API keys for server-to-server communication are available on the Pro plan and above.

### 1.1 Token Endpoint

POST to `/auth/token` with your `client_id` and `client_secret`.

### 1.2 Rate Limits by Plan

Rate Limits per Plan Tier
Plan | Requests/minute | Requests/day | Burst Limit | Price/month
--- | --- | --- | --- | ---
Free | 60 | 10,000 | 100 | $0
Starter | 300 | 100,000 | 500 | $49
Pro | 1,000 | 500,000 | 2,000 | $199
Enterprise | 10,000 | Unlimited | 20,000 | Custom

## 2. Core Endpoints

### 2.1 Documents API

Document Endpoints
Method | Endpoint | Description | Auth Required | Rate Limit
--- | --- | --- | --- | ---
GET | /documents | List all documents | Yes | Standard
POST | /documents | Upload a new document | Yes | 10/min
GET | /documents/{id} | Get document by ID | Yes | Standard
DELETE | /documents/{id} | Delete document | Yes (Owner) | Standard
POST | /documents/{id}/parse | Trigger AI parsing | Yes | 5/min
GET | /documents/{id}/sections | Get parsed sections | Yes | Standard

### 2.2 Search API

Search Endpoints
Method | Endpoint | Description | Max Results
--- | --- | --- | ---
POST | /search | Full-text semantic search | 100
POST | /search/hybrid | BM25 + vector hybrid search | 50
GET | /search/suggest | Autocomplete suggestions | 10

## 3. Error Codes

All errors follow RFC 7807 Problem Details format.

HTTP Error Code Reference
Code | Name | Common Cause | Resolution
--- | --- | --- | ---
400 | Bad Request | Invalid JSON or missing required field | Check request body schema
401 | Unauthorized | Missing or expired token | Refresh access token
403 | Forbidden | Insufficient permissions | Check plan limits or ownership
404 | Not Found | Resource ID does not exist | Verify document/resource ID
429 | Too Many Requests | Rate limit exceeded | Implement exponential backoff
500 | Internal Server Error | Platform error | Retry after 30s, contact support
503 | Service Unavailable | Planned maintenance | Check status.nexus.io

## 4. Webhooks

NexusAPI supports webhooks for async notifications. Register a URL via POST /webhooks. Payloads are signed with HMAC-SHA256 using your webhook secret. You must respond with HTTP 200 within 10 seconds or the delivery is retried up to 5 times with exponential backoff starting at 30 seconds.

### 4.1 Webhook Events

Available Webhook Events
Event | Trigger | Payload Size (max)
--- | --- | ---
document.parsed | AI parsing completes | 64 KB
document.deleted | Document removed | 4 KB
search.completed | Async search done | 256 KB
quota.warning | 80% of daily quota used | 4 KB
quota.exceeded | Daily quota exhausted | 4 KB

## 5. SDKs & Libraries

Official SDKs are available for Python, JavaScript/TypeScript, Go, and Java. Community-maintained SDKs exist for Ruby, PHP, and Rust.

Official SDK Versions
Language | Package | Latest Version | Min Runtime
--- | --- | --- | ---
Python | nexus-sdk | 3.4.1 | Python 3.9+
JavaScript | @nexus/sdk | 3.4.2 | Node 18+
Go | github.com/nexus-io/sdk-go | 3.3.0 | Go 1.21+
Java | io.nexus:nexus-sdk | 3.2.1 | Java 17+