API Reference
The canonical Opensolr API documentation lives in the FAQ knowledge base, organised by endpoint category. Each category is a dedicated section under /learn/api-* with full request/response examples, parameter tables, error codes, and code samples per endpoint. This page is the directory — pick the category you need.
API Endpoint Categories
Each link below is a full FAQ section with one article per endpoint. Browse the category that matches what you need to do.
Index Management
List, create, reload, delete, and inspect Opensolr indexes. Configure replication, set parent/child relationships, and manage index lifecycle.
Data Ingestion
Push documents into your index via REST. Includes the /api/ingest endpoint, file uploads with automatic text extraction (PDF, DOCX, etc.), bulk JSON ingestion, and queue inspection.
Config Files
Upload, list, and edit your index's schema.xml, solrconfig.xml, synonyms.txt, stopwords.txt, protwords.txt, and other configuration files. Includes auto-validation and live core reload.
Security
Manage HTTP Basic Auth credentials, IP whitelist, password protection on the search UI, and per-endpoint rate limits programmatically.
Backup Management
Create, list, restore, and delete index backups. Schedule daily backups and download snapshots.
Cluster Management
Replication operations, master/leader and follower configuration, multi-server topology, force-resync, replica health.
Logs & Analytics
Query the request log, analyse traffic by IP / path / query / HTTP status, export to CSV. The same data backs the Bandwidth and Query Analytics tabs in the dashboard.
Web Crawler
Start, stop, schedule, configure, and monitor crawls programmatically. Includes seed URL management, exclusion patterns, and crawl status reporting.
AI & Vector Endpoints
The vector embedding API, Hybrid Search, AI Hints, and AI Reader endpoints are documented in the AI / NLP FAQ section. These features require a vector-enabled / AI-enabled custom plan — see the AI Features Pricing page for details.
Authentication
Every API call needs your email (the address you registered with) and your api_key (find it in your dashboard under Account Settings). Both are sent as POST/GET parameters — not headers. Some endpoints (sitemap registration, account summary, settings dashboard) additionally require an HMAC-SHA256 signature derived from your API key.
For full details on signing requests, rotating API keys, and managing per-index HTTP Basic Auth credentials, see the Security FAQ section.
Rate Limits
The API enforces three tiers of limits, applied per Opensolr account:
The API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. Your application should back off and retry.
You can monitor your current usage programmatically via the Traffic Monitoring API, or visually in the Bandwidth Usage and Query Analytics tabs of your Index Control Panel.
Error Responses
Every endpoint returns a standard HTTP status code and a JSON body. Per-endpoint error semantics are documented in each FAQ article; the common HTTP codes:
| HTTP Code | Meaning | What to Do |
|---|---|---|
200 | Success. | Parse the JSON response body. |
400 | Bad Request — missing required parameters or invalid values. | Check the error message; fix your request parameters. |
401 | Unauthorized — email or API key is incorrect. | Verify credentials match your dashboard. |
403 | Forbidden — you do not have permission for this action. | Verify you own the index and are using the right account. |
404 | Not Found — endpoint or resource does not exist. | Check the URL for typos; verify the index name exists. |
429 | Too Many Requests — rate limit hit. | Wait for the seconds in Retry-After, then retry. |
500 | Internal Server Error. | Retry; if persistent, open a ticket via opensolr.com/contact. |
Error response shape
Code Examples
Copy-paste-ready, end-to-end implementations live in the dedicated Code Examples FAQ section. Pick the one closest to what you are building:
- Code Examples index — full topic listing.
- Complete Search Page (End-to-End) — single HTML file with search box, results & highlighting, pagination, language facet sidebar, autocomplete, spellcheck. Browser-only, eDisMax keyword search, CORS-enabled.
- Build Your Own Search UI (Hybrid) — PHP and Node.js examples, full keyword + vector flow via the Embed API. Uses the same parameters as the built-in Opensolr Search UI.
The entire Opensolr documentation set — every doc, FAQ, blog post, and code example — is itself indexed and searchable at search.opensolr.com/opensolr.