Push Endpoint

A Push Endpoint data source lets you update specific document records in the index on an ongoing and as-needed basis, instead of (or in addition to) periodically crawling other types of datasources. Records are available to users quickly, within about 15 seconds.

Note
The maximum file size of files you can push to a Push Endpoint data source is 5 MB. Push Endpoint data sources don’t index files that exceed 5 MB.

Add a push endpoint

  1. In the Site Search menu, click Add new data source, and then click Push Endpoint.

    Site Search sets up the push endpoint for you.

  2. (Optional) Change the last part of the push endpoint URI. A push endpoint URI has the following format:

    https://subdomain.lucidworks.cloud/pathname/api/v1/push/endpoint-name
  3. Click Copy to copy the push endpoint URI to the clipboard. Click Copy as Curl to copy a curl command that posts to the URI. The command has a sample JSON payload, which you will need to edit. In particular, notice that:

    • It is useful to provide values for the fields id, name, and description, because Site Search knows what to do with those out-of-the-box in the result template for result lists. The id field must be a string field.

    • You must include the API key that you’ll generate in the next step.

    • A more complete example of the JSON payload is farther down on the page in the section Posting JSON.

  4. Click Generate a New Key to generate an API key for the push endpoint. You’ll need to include the API key in the POST requests that send JSON documents to the push endpoint.

    Your API key is listed. Click Download API key to download a push-api-key.json file that contains the key. Or write the key down or copy it somewhere. It won’t be shown again.

  5. Under Posting JSON, Site Search displays an example of JSON to post. The fields listed are a superset of fields for all data sources. If you have different fields, you might want to map those fields to these names. Alternatively, when configuring result templates, you can reference your own field names. Click See more fields to see the whole JSON object.

    To copy the sample JSON object, hover over it and click Copy. Click Copy as Curl to copy the curl command to post to the push endpoint, with the JSON object as the payload.

  6. Click Save.

  7. Specify information on the Display tab (how to display results):

    1. (Optional) Choose a result template. Site Search has already chosen the best result template based on your data source, which is shown in the dropdown next to Edit Template. If you want to choose a different result template, you can.

    2. (Optional) Click Edit Template to edit the result template.

  8. If you have modified anything on the Display tab, click Save to save your changes.

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 the data source.

Create a Push API key

To create a Push API key
  1. In the Site Search menu, click the Push Endpoint data source for which you want to manage Push API keys.

  2. Click Generate a New Key to generate an API key for the push endpoint. You’ll need to include the API key in the POST requests that send JSON documents to the push endpoint.

    Your API key is listed. Click Download API key to download a push-api-key.json file that contains the key. Or write the key down or copy it somewhere. It won’t be shown again.

  3. Under Posting JSON, Site Search displays an example of JSON to post. The fields listed are a superset of fields for all data sources. If you have different fields, you might want to map those fields to these names. Alternatively, when configuring result templates, you can reference your own field names. Click See more fields to see the whole JSON object.

    To copy the sample JSON object, hover over it and click Copy. Click Copy as Curl to copy the curl command to post to the push endpoint, with the JSON object as the payload.

  4. Click Save.

Enter or update a key’s comment (description)

To enter or update a key’s comment
  1. In the Site Search menu, click the Push Endpoint data source for which you want to edit a key’s comment.

  2. Click in the Comment field of the Push API key for which you want to enter or update the comment.

  3. Enter the comment.

Delete a key

To delete a key
  1. In the Site Search menu, click the Push Endpoint data source for which you want to delete a key.

  2. Hover over the Push API key you want to delete, and then click Delete Delete.

Sample JSON object or curl command

Copy the sample JSON object or a curl command that posts the object to the push endpoint. This is an example of a curl command:

curl https://subdomain.lucidworks.cloud/search/api/v1/push/push-endpoint-prod -X POST -H "Content-Type: application/json" -d "{\"id\": \"ABf414\", \"name\":  \"Site Search\",  \"description\": \"Site Search is an embeddable, easy-to-configure, out-of-the-box site search solution.\", \"url\": \"https://lucidworks.com/products/site-search/\"}" -H "X-API-Key: 11b073a2-8465-4567-b5ce-2117eff2181e9227a690-f753-42d8-b942-16b28325f840"

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.

For information about API details, see Push new documents.

Update 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.

For information about API details, see Update 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).

For information about API details, see Delete documents.