This page is a quick reference for all Opensolr API endpoints. For in-depth documentation with request/response examples, error handling, and best practices, visit the Opensolr FAQ & Knowledge Base which contains dedicated articles for every endpoint.
Authentication
Every API request must be authenticated to prove that it comes from you, not an impersonator. Opensolr uses HMAC-signed requests — a standard, secure method where each request includes a cryptographic signature calculated from your API key.
Required Parameters
Every API call needs these two values, which you can find in your Opensolr dashboard under Account Settings:
| Parameter | Description | Example |
|---|---|---|
email | Your Opensolr account email address | you@example.com |
api_key | Your secret API key (never share this publicly) | 63dd168fa950... |
Example: Basic Authenticated Request
Your API key is like a password. Never put it in client-side JavaScript, public repositories, or anywhere visible to end users. Use environment variables or a secure secrets manager on your server.
API Endpoint Categories
The Opensolr API is organized into logical categories. Click any category below to jump to its detailed endpoint list.
Index Management
Create, delete, reset, reload, and replicate your Opensolr Indexes.
Document Operations
Commit changes, optimize, and delete documents from your index.
Web Crawler
Start, stop, and manage web crawls. Add or remove URLs from the crawl queue.
Data Ingestion
Upload and process documents (PDF, Word, HTML, etc.) into your index.
Vector / AI
Generate embeddings, perform vector searches, and get AI-powered summaries.
Backup & Restore
Create backups, restore from backups, and list available backup files.
Security
Manage HTTP authentication and IP whitelisting for your indexes.
Configuration
Upload, delete, and list configuration files for your Opensolr Indexes.
Index Management
These endpoints let you create, delete, reset, reload, replicate, and inspect your Opensolr Indexes programmatically.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/create_index | Create a new Opensolr Index with the specified name and configuration. Docs | index_name, plan |
DELETE | /api/delete_index | Permanently delete an Opensolr Index and all its data. Docs | index_name |
POST | /api/reset_index | Wipe all documents from an index while keeping its configuration intact. | index_name |
POST | /api/reload_core | Reload an index to pick up configuration changes without downtime. Docs | index_name |
POST | /api/replicate_index | Create a replica of an index on another server for high availability. | index_name, target_server |
GET | /api/get_core_status | Get the current status of a specific index (document count, size, uptime). | index_name |
GET | /api/get_index_list | List all Opensolr Indexes in your account. | — |
GET | /api/get_env | Get the server environment details for your index (hostname, version). | index_name |
Document Operations
Use these endpoints to commit pending changes, optimize index performance, and delete documents that match a query.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/commit | Commit all pending document additions/updates so they become searchable. Docs | index_name |
POST | /api/optimize | Optimize the index for faster search performance (merges segments). Docs | index_name |
GET | /api/optimize_status | Check whether an optimization is currently running or completed. | index_name |
POST | /api/delete_by_query | Delete all documents matching a Solr query (e.g. category:old). | index_name, query |
Web Crawler
The web crawler automatically visits your website, extracts content, and indexes it. These endpoints let you control crawl operations and manage the URL queue.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/start_crawl | Start a new crawl session for your website. Docs | index_name, seed_url |
POST | /api/stop_crawl | Stop a running crawl immediately. Docs | index_name |
POST | /api/pause_crawl | Pause a running crawl (can be resumed later). | index_name |
GET | /api/crawler_active | Check if a crawl is currently running for the given index. | index_name |
GET | /api/crawl_schedule_status | Get the current crawl schedule configuration. | index_name |
GET | /api/get_crawl_stats | Get crawl statistics: pages crawled, errors, queue size. | index_name |
POST | /api/add_crawl_url_signed | Add a URL to the crawl queue with HMAC signature verification. | index_name, url, signature |
DELETE | /api/delete_crawler_url | Remove a specific URL from both the crawled and queued tables. | index_name, url |
POST | /api/flush_crawl_buffer | Flush the crawler's staging buffer, pushing all pending pages to the index. | index_name |
Data Ingestion
Data ingestion lets you upload files (PDF, Word, Excel, HTML, and more) which Opensolr automatically extracts text from and indexes. The ingestion queue processes files in the background.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/ingest | Upload a file for text extraction and indexing. Docs | index_name, file (multipart) |
GET | /api/ingest_status | Check the status of a specific ingestion job. | index_name, job_id |
GET | /api/ingest_queue | List all items currently in the ingestion queue. | index_name |
POST | /api/ingest_queue_action | Perform an action on a queued item (retry, cancel, prioritize). | index_name, job_id, action |
POST | /api/ingest_run_now | Immediately process the next item in the ingestion queue. | index_name |
Vector / AI
These endpoints power Opensolr's AI capabilities. Generate vector embeddings from text, perform semantic (meaning-based) searches, and get AI-generated summaries of search results.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/embed | Generate a vector embedding from a single text string. Docs | text, model (optional) |
POST | /api/batch_embed | Generate vector embeddings for multiple texts in one request. | texts[], model (optional) |
POST | /api/embed_and_search | Embed your query text and immediately search for similar documents. | index_name, text, rows |
POST | /api/ai_summary | Get an AI-generated summary of search results for a query. Docs | index_name, query |
Backup & Restore
Protect your data by creating backups that you can restore at any time. Backups capture the entire state of your index — documents, configuration, everything.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/create_backup | Create a full backup of the specified index. Docs | index_name |
POST | /api/restore_backup | Restore an index from a previously created backup file. | index_name, backup_file |
GET | /api/get_backup_files_list | List all available backup files for the specified index. | index_name |
Security
Protect your Opensolr Indexes with HTTP Basic Authentication (username/password) and IP address whitelisting. Only authorized users or servers can access your data.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/update_http_auth | Set or update HTTP Basic Auth credentials for an index. Docs | index_name, username, password |
POST | /api/remove_http_auth | Remove HTTP Basic Auth from an index (makes it publicly accessible). | index_name |
POST | /api/add_ip | Add an IP address to the whitelist for an index. | index_name, ip |
DELETE | /api/delete_ip | Remove an IP address from the whitelist. | index_name, ip |
GET | /api/get_ip_list | List all whitelisted IP addresses for the specified index. | index_name |
Configuration
Manage the Solr configuration files for your indexes. Upload custom schema files, synonyms, stopwords, and other config files.
| Method | Endpoint | Description | Key Parameters |
|---|---|---|---|
POST | /api/upload_config_file | Upload a configuration file (e.g. synonyms.txt, schema.xml). Docs | index_name, file (multipart), filename |
DELETE | /api/delete_config_file | Delete a configuration file from your index. | index_name, filename |
GET | /api/get_all_config_files | List all configuration files currently in your index. | index_name |
Rate Limits
To ensure fair usage and protect the platform for everyone, API requests are rate-limited. Limits are applied at three levels:
The API returns a 429 Too Many Requests response. Your application should wait and retry. The response includes a Retry-After header telling you exactly how many seconds to wait before trying again.
If you need higher limits for your use case, contact support@opensolr.com — custom rate limits are available for Enterprise plans and on a case-by-case basis. You can also monitor your current usage programmatically via the Traffic Monitoring API.
Error Responses
When something goes wrong, the API returns a standard HTTP status code along with a JSON body explaining the error. Here are the most common ones:
| HTTP Code | Meaning | What to Do |
|---|---|---|
200 | Success — your request was processed correctly. | Parse the JSON response body for your data. |
400 | Bad Request — your request is missing required parameters or has invalid values. | Check the error message in the response. Fix your request parameters. |
401 | Unauthorized — your email or API key is incorrect. | Double-check your credentials. Make sure they match what is in your dashboard. |
403 | Forbidden — you do not have permission for this action (e.g., wrong index owner). | Verify you are using the correct account and that you own the index. |
404 | Not Found — the endpoint or resource does not exist. | Check the endpoint URL for typos. Verify the index name exists. |
429 | Too Many Requests — you have exceeded your rate limit. | Wait the number of seconds indicated in the Retry-After header, then retry. |
500 | Internal Server Error — something went wrong on our side. | Retry after a few seconds. If it persists, contact support@opensolr.com. |
Error Response Format
Code Examples
Here are complete, copy-paste-ready examples for the most common API operations.
1. List All Your Indexes
2. Create a New Index
3. Ingest a Document
4. Perform a Vector Search
5. Delete Documents by Query
If you run into any issues or need guidance integrating the Opensolr API into your application, reach out to support@opensolr.com. We are happy to help with code reviews, architecture advice, and debugging.