Workplace Search APIs
editWorkplace Search APIs
editFor performance and historical reasons, Workplace Search has some default limitations. Refer to the Enterprise Search configuration documentation for details.
To make a request to the Workplace Search API, use the workplace
property of the client
object, followed by the desired method.
Refer to the Workplace Search API reference to find the full HTTP API endpoints documentation.
On this page
Initializing the client
editSee Import and instantiate the client for details on initializing the client.
Note that Workplace Search also has its own application-specific API keys and tokens. Refer to Authentication for more information and relevant links.
Documents APIs
editTo ingest documents into Workplace Search with the API you must first create a Custom Content Source and get the Content Source ID and Content Source Access Token.
Create or update documents
editTo create or update documents, use the indexDocuments()
method:
async function run () { const indexDocuments = await client.workplace.indexDocuments( {content_source_id: '63c5382093f3219aa08a7202', documents:[ { "_allow_permissions": [], "_deny_permissions": [], "id" : 1234, "title" : "The Meaning of Time", "body" : "Not much. It is a made up thing.", "url" : "https://example.com/meaning/of/time", "created_at": "2019-06-01T12:00:00+00:00", "type": "list" }, { "_allow_permissions": [], "_deny_permissions": ["permission2"], "id" : 1235, "title" : "The Meaning of Sleep", "body" : "Rest, recharge, and connect to the Ether.", "url" : "https://example.com/meaning/of/sleep", "created_at": "2019-06-01T12:00:00+00:00", "type": "list" } ]}) if (indexSource.errors) { console.log(indexSource) process.exit(1) } console.log(indexSource)} run().catch(console.log)
Get documents
editTo get a single document by ID use the getDocuments()
method:
async function run () { const getDocument = await client.workplace.getDocument( {content_source_id: '63c5382093f3219aa08a7202', document_id: '1235'}) if (getDocument.errors) { console.log(getDocument) process.exit(1) } console.log(getDocument)} run().catch(console.log)
List documents
editTo list all documents in a content source, use the listDocuments()
method:
async function run () { const listDocuments = await client.workplace.listDocuments( {content_source_id: '63c5382093f3219aa08a7202'}) if (listDocuments.errors) { console.log(listDocuments) process.exit(1) } console.log(listDocuments)} run().catch(console.log)
Delete documents
editTo delete documents by ID use the deleteDocuments()
method, and supply a list of document IDs to body
:
async function run () { const deleteDocuments = await client.workplace.deleteDocuments( {content_source_id: '63c5382093f3219aa08a7202', document_ids: ['1235'] }) if (deleteDocuments.errors) { console.log(deleteDocuments) process.exit(1) } console.log(deleteDocuments)} run().catch(console.log)
A successful response returns:
{ results: [ { id: '1235', success: true } ] }
Delete documents by query
editTo delete documents that match a query or filters, use the deleteDocumentsByQuery()
method:
async function run () { const deleteDocumentsByQuery = await client.workplace.deleteDocumentsByQuery( {content_source_id: '63c5382093f3219aa08a7202', body: { "query": "meaning of time" }}) if (deleteDocumentsByQuery.errors) { console.log(deleteDocumentsByQuery) process.exit(1) } console.log(deleteDocumentsByQuery)} run().catch(console.log)
Delete all documents in a content source
editTo delete all documents in a content source, use the deleteDocumentByQuery()
method, omitting the body
parameter:
async function run () { const deleteAllDocuments = await client.workplace.deleteDocumentsByQuery( {content_source_id: '63c5382093f3219aa08a7202'}) if (deleteAllDocuments.errors) { console.log(deleteAllDocuments) process.exit(1) } console.log(deleteAllDocuments)} run().catch(console.log)
Content sources APIs
editRefer to the Content sources API reference for the full HTTP API documentation.
Create a content Source
editTo create a content source, use the createContentSource()
method:
async function run () { const createSource = await client.workplace.createContentSource( {body: { name: 'My Custom Content Source', type: 'custom', }}) if (createSource.errors) { console.log(createSource) process.exit(1) } console.log(createSource)} run().catch(console.log)
Expand to see an example response
{ id: '63c52f7893f321f78d8a718f', service_type: 'custom', created_at: '2023-01-16T11:05:28+00:00', last_updated_at: '2023-01-16T11:05:28+00:00', is_remote: false, details: [], groups: [ { id: '63b55500a336df401de08857', name: 'Default' } ], name: 'My Content Source', context: 'organization', is_searchable: true, facets: { overrides: [] }, automatic_query_refinement: { overrides: [] }, schema: {}, display: { title_field: '', subtitle_field: '', description_field: '', url_field: '', type_field: '', media_type_field: '', created_by_field: '', updated_by_field: '', detail_fields: [], color: '#000000' }, document_count: 0, last_indexed_at: null }
List content sources
editTo list all content sources, use the listContentSources()
method:
async function run () { const listSources = await client.workplace.listContentSources() if (listSources.errors) { console.log(listSources) process.exit(1) } console.log(listSources)} run().catch(console.log)
Expand to see an example response
{ meta: { page: { current: 1, total_pages: 1, total_results: 1, size: 25 } }, results: [ { id: '63b6a3cb93f321b0d789fbcb', service_type: 'dropbox', created_at: '2023-01-05T10:17:47+00:00', last_updated_at: '2023-01-05T10:17:47+00:00', is_remote: false, details: [], groups: [Array], name: 'Dropbox', context: 'organization', is_searchable: true, indexing: [Object], facets: [Object], automatic_query_refinement: [Object], schema: [Object], display: [Object], document_count: 0, last_indexed_at: null } ] }
Get a content Source
editTo retrieve a content source, use the getContentSource()
method:
async function run () { const getSource = await client.workplace.getContentSource( {content_source_id: '63b6a3cb93f321b0d789fbcb'}) if (getSource.errors) { console.log(getSource) process.exit(1) } console.log(getSource)} run().catch(console.log)
Update a content Source
editTo update a content source, use the putContentSourcet()
method:
async function run () { const updateSource = await client.workplace.putContentSource( {content_source_id: '63c52f7893f321f78d8a718f', body: { name: 'My Content Source', type: 'custom', schema: {'title': 'text', 'body': 'text', url: 'text'}, display: {title_field: 'title', url_field: 'url', color: '#000000'}, is_searchable: true, }}) if (updateSource.errors) { console.log(updateSource) process.exit(1) } console.log(updateSource)} run().catch(console.log)
Expand to see an example response
{ id: '63c52f7893f321f78d8a718f', service_type: 'custom', created_at: '2023-01-16T11:05:28+00:00', last_updated_at: '2023-01-16T11:37:18+00:00', is_remote: false, details: [], groups: [ { id: '63b55500a336df401de08857', name: 'Default' } ], name: 'My Content Source', context: 'organization', is_searchable: true, facets: { overrides: [] }, automatic_query_refinement: { overrides: [] }, schema: { title: 'text', body: 'text', url: 'text' }, display: { title_field: 'title', subtitle_field: null, description_field: null, url_field: 'url', type_field: null, media_type_field: null, created_by_field: null, updated_by_field: null, detail_fields: [], color: '#000000' }, document_count: 0, last_indexed_at: null }
Delete a content Source
editTo delete a content source, use the deleteContentSource()
method:
async function run () { const deleteSource = await client.workplace.deleteContentSource( {content_source_id: '63c52f7893f321f78d8a718f'}) if (deleteSource.errors) { console.log(deleteSource) process.exit(1) } console.log(deleteSource)} run().catch(console.log)
A successful response returns:
{ deleted: true }
Search APIs
editRefer to the Search API reference for the full HTTP API documentation.
To search for documents that match a query, use the search()
method:
async function run () { const search = await client.workplace.search( {body: { query: 'sleep' }}) if (search.errors) { console.log(search) process.exit(1) } console.log(search)} run().catch(console.log)
Expand to see an example response
{ meta: { page: { current: 1, total_pages: 1, total_results: 1, size: 10 }, warnings: [], sources: { '63b6a3cb93f321b0d789fbcb': [Object], '63c5382093f3219aa08a7202': [Object] }, request_id: 'EZiRxYisQ4KhKS8j-Tpi7g' }, results: [ { last_updated: [Object], _meta: [Object], updated_at: [Object], created_at: [Object], content_source_id: [Object], source: [Object], id: [Object], title: [Object], body: [Object], type: [Object], url: [Object] } ] }
Get current user
editTo get the current user, use the getCurrentUser()
method:
async function run () { const user = await client .workplace .getCurrentUser() console.log(user)} run().catch(console.log)
A successful response returns:
{ email: 'john.doe@elastic.co', username: 'elastic' }
Synonyms APIs
editRefer to the Synonyms API reference for the full HTTP API documentation.
Create synonym Set
editTo create a synonym set, use the createBatchSynonymSets()
method:
async function run () { const createSynonyms = await client.workplace.createBatchSynonymSets( {body: { synonym_sets: [ { synonyms: ['sleep', 'rest', 'nap'], }, { synonyms: ['work', 'job', 'career'], } ] }}) if (createSynonyms.errors) { console.log(createSynonyms) process.exit(1) } console.log(createSynonyms.synonym_sets)} run().catch(console.log)
Expand to see an example response
{ has_errors: false, synonym_sets: [ { id: '63c5552693f3212ca28a7376', synonyms: [Array] }, { id: '63c5552693f3212ca28a7377', synonyms: [Array] } ] }
Get synonym Set
editTo get a synonym set, use the getSynonymSet()
method, passing the synonym_set_id
:
async function run () { const getSynonyms = await client.workplace.getSynonymSet( {synonym_set_id:'63c5552693f3212ca28a7376'}) if (getSynonyms.errors) { console.log(getSynonyms) process.exit(1) } console.log(getSynonyms)} run().catch(console.log)
Expand to see an example response
{ id: '63c5552693f3212ca28a7376', synonyms: [ 'sleep', 'rest', 'nap' ], created_at: '2023-01-16T13:46:14Z', updated_at: '2023-01-16T13:46:14Z' } { id: '63c5552693f3212ca28a7376', synonyms: [ 'sleep', 'rest', 'nap' ], created_at: '2023-01-16T13:46:14Z', updated_at: '2023-01-16T13:46:14Z' }
List synonym sets
editTo list all synonym sets, use the listSynonymSets()
method:
async function run () { const listSynonyms = await client.workplace.listSynonymSets() if (listSynonyms.errors) { console.log(listSynonyms) process.exit(1) } console.log(listSynonyms)} run().catch(console.log)
Expand to see an example response
{ meta: { page: { current: 1, total_pages: 1, total_results: 2, size: 25 }, sort: { updated_at: 'desc' } }, results: [ { id: '63c5552693f3212ca28a7376', synonyms: [Array], created_at: '2023-01-16T13:46:14Z', updated_at: '2023-01-16T13:46:14Z' }, { id: '63c5552693f3212ca28a7377', synonyms: [Array], created_at: '2023-01-16T13:46:14Z', updated_at: '2023-01-16T13:46:14Z' } ] }
Update synonym set
editTo update a synonym set, use the putSynonymSet()
method, passing the synonym_set_id
:
async function run () { const updateSynonyms = await client.workplace.putSynonymSet( {synonym_set_id:'63c5552693f3212ca28a7376', body: { synonyms: ['sleep', 'rest', 'nap', 'dream'] }}) if (updateSynonyms.errors) { console.log(updateSynonyms) process.exit(1) } console.log(updateSynonyms)} run().catch(console.log)
A successful response looks like this:
{ id: '63c5552693f3212ca28a7376', synonyms: [ 'sleep', 'rest', 'nap', 'dream' ] }
Delete synonym set
editTo delete a synonym set, use the deleteSynonymSet()
method, passing the synonym_set_id
:
async function run () { const deleteSynonyms = await client.workplace.deleteSynonymSet( {synonym_set_id:'63c5552693f3212ca28a7376'}) if (deleteSynonyms.errors) { console.log(deleteSynonyms) process.exit(1) } console.log(deleteSynonyms)} run().catch(console.log)
A successful response returns:
{ deleted: true }