IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« App Search APIs Enterprise Search management APIs »

›

Workplace Search APIs

edit

Workplace Search APIs

edit

For 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

edit

See 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

Refer to the Content sources API reference for the full HTTP API documentation.

Create a content Source

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

Refer 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

edit

To 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

edit

Refer to the Synonyms API reference for the full HTTP API documentation.

Create synonym Set

edit

To 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

edit

To 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

edit

To 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

edit

To 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

edit

To 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 }

« App Search APIs Enterprise Search management APIs »