Push

Manage Push API keys

To submit a request to the Push API, an app must include a valid Push API key in an X-API-Key header in the HTTP request.

Manage Push API keys in the Admin UI. Select a Push Endpoint data source to manage Push API keys for that data source. Push API keys are specific to data sources (each data source can have one or more Push API keys).

Note
You must specify the push endpoint and API key for a specific push endpoint. If there is more than one Push Endpoint data source then, when updating or deleting documents, you must know with which data source documents are associated.

Push new documents

Use the Push API to push new documents to a Push Endpoint data source. A document is taken to be new if no documents in the index have a matching id field. Site Search adds the new records to the index.

The format of the document payload in the request is JSON. You can push documents one at a time, or push multiple documents in a single JSON document.

JSON payload requirements and recommendations

Note the following requirements and recommendations for the JSON payload:

  • In the JSON payload, id and name are required fields. These fields must be string fields (surround each field in escaped double quotation marks). For example:

    { "id": "doc-id-1", "name": "Document name 1", "description": "test doc", "url": "http://url_to_doc_id1" }
  • You can include any other fields that you like. We recommend that you include description and url fields. These fields help Site Search do intelligent things with the pushed records.

  • The fields can be in any order.

Makeup of a push request

A push request for adding a new document has these parts:

  • A Push API key – Use a Push API key for the Push Endpoint data source to which you want to push the document. Site Search uses the Push API key to authorize the request.

  • HTTP request header – An X-API-Key request header contains the Push API key.

  • REST verb – Push uses the REST verb POST.

  • REST endpoint – Use the REST endpoint for the Push API data source to which you want to push the document.

  • Request parameters – The API request has no parameters. Identify the document payload for the POST, for example, using the -d parameter in curl.

  • A reference to a JSON file (or a JSON payload in the request) that contains a single document or multiple documents.

HTTP request header

An HTTP request for the Search API must contain the X-API-Key header, a custom HTTP header to contain the Search API key.

REST verb

The REST verb for pushing documents is POST.

Push API endpoint

The URI of the Push API endpoint is:

https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint
Note
You must specify the push endpoint and API key for a specific push endpoint. If there is more than one Push Endpoint data source then, when updating or deleting documents, you must know with which data source documents are associated.

Request parameters

The API request has no parameters. Identify the JSON document payload for the POST, for example, using the -d parameter in curl.

JSON syntax for pushing a single document

A JSON file for a request to push a single document contains a single JSON object that specifies the fields and values of the single document as key/value pairs.

This is the syntax:

{"id": "value", "name": "value", "field3": "value", "field4": "value", ...}

This is an example:

{"id": "doc-id-1", "name": "Document name 1", "description": "An example", "url": "https://www.example.com"}

JSON syntax for pushing multiple documents

A JSON file for a request to push multiple documents contains a single JSON array of JSON objects. Each JSON object specifies the fields and values of a single document as key/value pairs.

This is the syntax:

[
  {"id": "id-value1", "name": "name-value1", "field3": "value", "field4": "value", ...},
  {"id": "id-value2", "name": "name-value2", "field3": "value", "field4": "value", ...},
  {"id": "id-value3", "name": "name-value3", "field3": "value", "field4": "value", ...},
  ...
  {"id": "id-valueN", "name": "name-valueN", "field3": "value", "field4": "value", ...}
]

This is an example:

[
  {"id": "doc-id-1", "name": "Document name 1", "description": "A doc website", "url": "https://www.docs.com"},
  {"id": "doc-id-2", "name": "Document name 2", "description": "A product website", "url": "https://www.products.com"}
]

Update existing documents

Use the Push API to push updated documents to a Push Endpoint data source. To update a document, push a document with the same value in the id field to the Push API endpoint for the same Push Endpoint data source.

The format of the document payload in the request is JSON. You can update documents one at a time, or update multiple documents in a single JSON document.

Makeup of a push request

A push request for updating a document has these parts:

  • A Push API key – Use a Push API key for the Push Endpoint data source to which you want to push the document. Site Search uses the Push API key to authorize the request.

  • HTTP request header – An X-API-Key request header contains the Push API key.

  • REST verb – Push uses the REST verb POST.

  • REST endpoint – Use the REST endpoint for the Push API data source to which the document was previously pushed.

  • Request parameters – The API request has no parameters. Identify the document payload for the POST, for example, using the -d parameter in curl.

  • A reference to a JSON file (or a JSON payload in the request) that contains a single document or multiple documents.

HTTP request header

An HTTP request for the Search API must contain the X-API-Key header, a custom HTTP header to contain the Search API key.

REST verb

The REST verb for pushing documents is POST.

Push API endpoint

The URI of the Push API endpoint is:

https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint

This is an example URL:

https://my-corp.lucidworks.cloud/fusion-search/api/v1/push/push-endpoint-prod/
Note
You must specify the push endpoint and API key for a specific push endpoint. If there is more than one Push Endpoint data source then, when updating or deleting documents, you must know with which data source documents are associated.

Request parameters

The API request has no parameters. Identify the JSON document payload for the POST, for example, using the -d parameter in curl.

JSON syntax

The JSON syntax for updating single documents is the same as for pushing new documents singly. For updating multiple documents, the syntax is the same as for pushing multiple new documents.

Delete documents

Use the Push API to delete document from a Push Endpoint data source (that is, to delete index entries for previously pushed documents). You must delete documents one at a time (one document per request).

You might want to delete documents, that is, to remove the index entries for previously pushed documents. To do this, you use the Push API endpoint and Push API key for the Push Endpoint data source to which the document was pushed, but with the verb DELETE instead of POST. You must delete documents one at a time.

Makeup of a deletion request

A push request for deleting a document has these parts:

  • A Push API key – Use a Push API key for the Push Endpoint data source to which you want to push the document. Site Search uses the Push API key to authorize the request.

  • HTTP request header – An X-API-Key request header contains the Push API key.

  • REST verb – Deleting a document uses the REST verb DELETE.

  • REST endpoint – Use the REST endpoint for the Push API data source from which you want to delete the document.

  • Request parameters – The API request has no parameters. Identify the document you want to delete by it’s ID, appended to the push endpoint URL.

HTTP request header

An HTTP request for the Search API must contain the X-API-Key header, a custom HTTP header to contain the Search API key.

REST verb

The REST verb for deleting documents is DELETE.

Push API endpoint

This is the syntax showing the push endpoint and the document ID:

https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint/id

This is an example URL:

https://my-corp.lucidworks.cloud/fusion-search/api/v1/push/push-endpoint-prod/Rec10023
Note
You must specify the push endpoint and API key for a specific push endpoint. If there is more than one Push Endpoint data source then, when updating or deleting documents, you must know with which data source documents are associated.

Request parameters

The API request has no parameters. Identify the document you want to delete by its ID, appended to the push endpoint URL.

Examples

The are Push API examples.

Push a single document

curl -X POST \
  https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{\"id\": \"doc-id-1\", \"name\": \"Document name 1\", \"description\": \"A test description\", \"url\": \"www.example.com\"}'

Push multiple documents

curl -X POST \
  https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '[
    {\"id\": \"doc1\", \"name\": \"Document name 1\", \"description\": \"A test description\", \"url\": \"www.example.com\"},
    {\"id\": \"doc2\", \"name\": \"Document name 2\", \"description\": \"Another description\", \"url\": \"www.other.com\"}
]'

Delete a document

curl -X DELETE \
  https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint/id \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Committing changes

For single documents and multiple documents, Site Search commits push requests as soon as they are received. By "commit," we mean making the changes in the data source.

For delete requests, Site Search groups incoming requests and commits them periodically (once a minute).

If you want to commit a deletion more quickly, you can include commit=true as a URL parameter in the deletion request. For example:

curl -X DELETE \
  https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint/id?commit=true \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Tip
If you submit multiple push requests, each for a single document, then not committing every deletion immediately is more efficient.