Your First Data Ingestion Push

One request puts your first document in your Opensolr Index. This page is the whole round trip: send, read the answer, follow the job, search.

Before you start

• An Opensolr Index on a site search server (What your index needs). Its name is the core_name below; index_name works too.
• Your account email and an API key from Account > API Keys (API authentication).

1. Send the documents

Send a POST to https://api.opensolr.com/solr_manager/api/ingest with a JSON body. Up to 50 documents go in one request.

curl -X POST "https://api.opensolr.com/solr_manager/api/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "api_key": "YOUR_API_KEY",
    "core_name": "YOUR_INDEX_NAME",
    "documents": [
      {
        "uri": "https://example.com/products/headphones-x2",
        "title": "Wireless Headphones X2",
        "description": "Noise cancelling over-ear headphones, 30 hours of battery.",
        "text": "The X2 headphones fold flat, pair with two devices at once and charge in 15 minutes.",
        "price_f": 79.99,
        "currency_s": "USD"
      }
    ]
  }'

Every document needs uri (its web address), title, description and text. All the fields: Document fields. A form post works too, with documents as a JSON string.

Data Ingestion answers only on api.opensolr.com. The same call on opensolr.com answers WRONG_API_HOST with the right address.

2. Read the answer

Opensolr checks the batch and answers at once:

{
  "status": true,
  "msg": "QUEUED",
  "job_id": "3f9c2a7e5b1d4c8a9e0f6b2d7c4a1e58",
  "total_docs": 1,
  "doc_ids": ["4a54e4dcd4f76c40f3345f1e3652cd18"]
}

• job_id is your job in the Data Ingestion queue.
• doc_ids holds the id of each document in your index, made from its uri. Keep them if you will delete documents later.
• total_docs is how many documents were queued. A document already waiting in the queue for this index is skipped, not queued twice.

When something is wrong, nothing is queued: status is false and msg says why. VALIDATION_ERRORS comes with an errors list, one line per faulty document. Every answer: Limits and refusals.

3. Follow the job

Open Account > Data Ingestion in your Opensolr account (The Data Ingestion queue), or ask the API:

curl "https://api.opensolr.com/solr_manager/api/ingest_status?email=you@example.com&api_key=YOUR_API_KEY&job_id=YOUR_JOB_ID"

The answer's job holds state_label (pending, processing, completed, failed, paused or stopped), the counts total_docs, processed_docs, success_docs and failed_docs, and, once the job is finished, result: a summary, with the reasons of any failed documents.

4. Search

When the job is completed, its documents are searchable seconds later: on your hosted search page, in your chat bot and through the API. A completed job can still hold failed documents; its result counts them and gives the reasons.

Technical reference of the ingest and ingest_status calls: Data Ingestion API.