Ingest API

Updated

The Ingest API writes documents into a Site Search index through update endpoints.

Endpoint

  • Method: POST
  • Primary path: /update
  • Common JSON convenience path: /update/json/docs

UI Navigation

Find this endpoint in Site Search > App Settings > Data Management > Ingest API.

Ingest API endpoint panel in Site Search app settings.

Authentication

Use write-capable credentials for ingest operations.

  • Token auth: Authorization: Token <read-write-token>
  • Basic auth: app user ID and password (when enabled for the app)

Note: Read-only credentials are not valid for write operations.

Request Parameters

Name Required Type Description
Authorization Yes header Use Authorization: Token <read-write-token> for write operations. Read-only credentials are not valid for ingest writes.
commit Recommended query boolean Commit indexed changes with the request. Examples commonly use commit=true.
wt No query string Response writer format. wt=json and wt=xml are accepted by the endpoint.
omitHeader No query boolean Omits the responseHeader object when set to true (useful for response size reduction).

Request Examples

Sample request (/update): 

curl -sS -X POST \
  -H "Authorization: Token <read-write-token>" \
  -H "Content-Type: application/json" \
  --data-binary '[{"id":"doc-1002","title":"Sample Update"}]' \
  "https://<update-host>/update?commit=true"

Sample request (/update/json/docs): 

curl -sS -X POST \
  -H "Authorization: Token <read-write-token>" \
  -H "Content-Type: application/json" \
  --data-binary '[{"id":"doc-1001","title":"Sample"}]' \
  "https://<update-host>/update/json/docs?commit=true"

Response Notes

Successful writes return a search update response envelope. Validation and parser failures return structured error payloads.

Sample success payload: 

{
  "responseHeader": {
    "status": 0,
    "QTime": 24
  }
}

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Write request succeeds Search update response envelope Confirm commit and write outcome
400 Request reaches parser but command or body is invalid Parser or validation error payload Correct payload schema and command
401 Credential type or token is invalid for write {"message":"Unauthorized"} Use valid write-capable credentials
413 Payload exceeds size limit Content-length limit message (10485760) Reduce payload size
414 Request line or URL is too large URI and request-too-large response Reduce query and request line size
429 Rate or plan limit condition Too-many-requests style response Retry with backoff and check usage
500 Service-side failure (can occur with overage conditions) Internal service error payload Check usage and limits, then escalate

Pagination

Not applicable for ingest write operations.

Rate Limits and Backoff

  • App-level request rate guidance: 20+ requests/second.
  • Effective payload limit: approximately 10 MB per request.
  • 429 responses do not reliably include Retry-After. Apply client-side retry delays.

Recommended backoff:

  • Short-lived failures: retry with increasing delays.
  • Persistent failures (429 or 500): verify account usage and contract limits.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section