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.
Two Hosts, One Path Scheme
Every endpoint is https://HOST/solr_manager/api/METHOD. Which host depends on what the method does:
opensolr.comcreate_index get_index_list upload_zip_config_files start_crawl update_http_auth create_backupapi.opensolr.comembed batch_embed embed_and_search embed_opensolr_index image_to_text ai_summary ingest ingest_status ingest_run_now ingest_queue*Calling an AI method on opensolr.com answers AI_API_IS_API.OPENSOLR.COM; calling a management method on api.opensolr.com answers 403 Forbidden. On api.opensolr.com the shorter https://api.opensolr.com/api/METHOD form is also accepted. Each FAQ article shows the correct host in its Endpoint box.
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. What is in that schema, field by field, is in the Vector Search Schema Reference.
Security
Set or remove HTTP Basic Auth credentials on an index (update_http_auth / remove_http_auth) and manage its IP access rules (add, list, remove) 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.
Geolocation
geo_lookup turns up to 50 IP addresses per call into country, region, city, coordinates and IANA timezone — for putting a location next to the addresses in your logs. nearby_places turns up to 50 GPS coordinate pairs into the nearest named place: city, region, province, community, country. Answers are kept for good, and neither draws on the AI allowance.
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 API FAQ section: embed, batch_embed, embed_and_search (hybrid search with your saved tuning), embed_opensolr_index ai_summary and image_to_text (search by image: a picture in, search words out). All of them live on api.opensolr.com. These features require a vector-enabled / AI-enabled plan — see the pricing page for details.
Browse the AI API documentation →
See image_to_text at work: nine screenshots of real searches on live indexes — a photo of two huskies against a jewellery catalogue, the same lily photo against three different indexes, and a shelf tag read off a store shelf.
Authentication
Every API call needs your email (the address you registered with) and an api_key. Both are sent as POST/GET parameters — not headers (JSON request bodies are accepted too, with the same field names). Four endpoints additionally require a hex HMAC-SHA256 signature keyed with your API key: get_account_summary and get_settings_dashboard sign core_name + email; add_crawl_url_signed and delete_crawler_url sign url + core_name.
Two kinds of key work here: your account master key (root-level, found in your dashboard) and a scoped key restricted to chosen endpoints and indexes, created under Account › API Keys. Prefer a scoped key whenever the caller does not need full access — see Master API Key vs Scoped API Keys.
Call any endpoint with the email mcp@opensolr.com and the api_key 420b8b23e7b12dc8ab838932145a5065. It comes with a preloaded index, mcp_demo_d1__dense (300 news articles), so your first call has something real to query. Anything you create there is deleted after 3 days, automatically. The account is shared publicly — other people can see what you create and add to it, though nothing here can be deleted or reconfigured through this key — and the limits are per index and small on purpose: 200 MB bandwidth, 50 MB disk. For a private index that persists, register a free account — free forever, no card.
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
Always check the status field of the JSON body — most application errors come back with HTTP 200 and "status": false. Only a few conditions change the HTTP status code:
200{"status": true, ...}msg (or endpoint-specific keys such as results, job_id, fields).200{"status": false, "msg": "ERROR_..."}ERROR_USER_IS_NOT_OWNER, NOT_OWNER_ERROR), a plan limit, a feature not enabled (FREE_OPENSOLR_ACCOUNTS_ARE_NOT_SUPPORTED_PLEASE_UPGRADE). Fix the request; the code in msg is documented per endpoint.403{"status": false, "msg": "ERROR_AUTHENTICATION_FAILED"}403ERROR_SCOPED_KEY_ENDPOINT_NOT_ALLOWED / ERROR_SCOPED_KEY_CORE_NOT_ALLOWED403api.opensolr.com (see Two Hosts above) — use opensolr.com.429{"status": false, "msg": "ERROR_RATE_LIMIT_..."} + Retry-After: 60404404500Error response shape
A handful of older endpoints return a plain-text or empty body instead of JSON (for example upload_zip_config_files streams its progress, delete_environment answers with an empty body on success). Each FAQ article shows the exact response of its endpoint.
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.