Search API (v2.1.0)

Search API

search

searchInstances

Get a list of instances for CQL query

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 500 ] Default: 100 Limit the number of elements returned in the response.
offset	integer [ 0 .. 9999 ] Default: 0 Skip over a number of elements by specifying an offset value for the query.
expandAll	boolean Default: false Whether to return only basic properties or entire instance.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

searchAuthorities

Get a list of authorities for CQL query

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 500 ] Default: 100 Limit the number of elements returned in the response.
offset	integer [ 0 .. 9999 ] Default: 0 Skip over a number of elements by specifying an offset value for the query.
expandAll	boolean Default: false Whether to return only basic properties or entire instance.
includeNumberOfTitles	boolean Default: true Whether to perform a search for a number of linked instances.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

search-resources-ids

getInstanceIds

Get a list of instance ids for CQL query

query Parameters

query

required

string

A CQL query string with search conditions.

header Parameters

x-okapi-tenant required	string X-Okapi-Tenant header value
Content-Type	string Content-Type header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/InstanceIdsResult.sample"

getHoldingIds

Get a list of holding ids linked to instances found by the CQL query

query Parameters

query

required

string

A CQL query string with search conditions.

header Parameters

x-okapi-tenant required	string X-Okapi-Tenant header value
Content-Type	string Content-Type header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/HoldingIdsResult.sample"

getIdsJob

Get a job for the stream of resource ids.

path Parameters

jobId

required

string

UUID of the job to get

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/streamIdsJobResponse.sample"

submitIdsJob

Creates a job for the stream of resource ids.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Request Body schema: application/json

id	string Unique ID for the job record.
query required	string CQL query for getting ids.
status	string Enum: "IN_PROGRESS" "ERROR" "COMPLETED" "DEPRECATED" Ids streaming status.
entityType required	string Enum: "INSTANCE" "AUTHORITY" "HOLDINGS" Type of entity for streaming ids.
createdDate	string Date and time when the record was created.

Responses

Request samples

Payload

Content type

application/json

"examples/streamIdsJobRequest.sample"

Response samples

200
400
500

Content type

application/json

"examples/streamIdsJobResponse.sample"

getResourceIds

Get a list of resource ids by job id

path Parameters

jobId

required

string

UUID of the job to get

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/resourceIdsResult.sample"

facets

getFacets

Provides list of facets for the record type

path Parameters

recordType

required

string (RecordType)

Enum: "instances" "authorities" "contributors" "subjects"

query Parameters

query required	string A CQL query string with search conditions.
facet required	Array of strings List of facet names.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/facetResult.sample"

search-consortium

getConsortiumHoldings

Get a list of holdings (only for consortium environment)

query Parameters

instanceId	string UUID of the instance
tenantId	string Tenant ID
limit	integer [ 0 .. 1000 ] Default: 100 Limit the number of elements returned in the response.
offset	integer [ 0 .. 9999 ] Default: 0 Skip over a number of elements by specifying an offset value for the query.
sortBy	string Defines a field to sort by. Possible values: id hrid tenantId instanceId callNumberPrefix callNumber callNumberSuffix copyNumber permanentLocationId
sortOrder	string (sortOrder) Enum: "asc" "desc" Defines sorting order

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

{"holdings": [{"id": "string",
"hrid": "string",
"tenantId": "string",
"instanceId": "string",
"discoverySuppress": true,
"callNumberPrefix": "string",
"callNumber": "string",
"callNumberSuffix": "string",
"copyNumber": "string",
"permanentLocationId": "string"
}
],
"totalRecords": 0
}

getConsortiumItems

Get a list of items (only for consortium environment)

query Parameters

instanceId	string UUID of the instance
holdingsRecordId	string UUID of the holdings record
tenantId	string Tenant ID
limit	integer [ 0 .. 1000 ] Default: 100 Limit the number of elements returned in the response.
offset	integer [ 0 .. 9999 ] Default: 0 Skip over a number of elements by specifying an offset value for the query.
sortBy	string Defines a field to sort by. Possible values: id hrid tenantId instanceId holdingsRecordId barcode
sortOrder	string (sortOrder) Enum: "asc" "desc" Defines sorting order

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

{"items": [{"id": "string",
"hrid": "string",
"tenantId": "string",
"instanceId": "string",
"holdingsRecordId": "string",
"barcode": "string"
}
],
"totalRecords": 0
}

browse

browseInstancesByCallNumber

Provides list of instances for browsing by call number

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 100 ] Default: 100 Limit the number of elements returned in the browse response.
expandAll	boolean Default: false Whether to return only basic properties or entire instance.
highlightMatch	boolean Default: true Whether to highlight matched resource by query input or not.
precedingRecordsCount	integer [ 1 .. 100 ] Number of preceding records for browsing around and around-including options
callNumberType	string (CallNumberType) Enum: "lc" "dewey" "nlm" "sudoc" "other" "local" Type of call number

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

browseInstancesByClassificationNumber

Provides list of instances for browsing by classification number

path Parameters

browseOptionId

required

string (browseOptionType)

Enum: "all" "lc" "dewey"

Browse option type

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 100 ] Default: 100 Limit the number of elements returned in the browse response.
expandAll	boolean Default: false Whether to return only basic properties or entire instance.
highlightMatch	boolean Default: true Whether to highlight matched resource by query input or not.
precedingRecordsCount	integer [ 1 .. 100 ] Number of preceding records for browsing around and around-including options

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

browseInstancesBySubject

Provides list of instances for browsing by subject

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 500 ] Default: 100 Limit the number of elements returned in the response.
highlightMatch	boolean Default: true Whether to highlight matched resource by query input or not.
precedingRecordsCount	integer [ 1 .. 100 ] Number of preceding records for browsing around and around-including options

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

browseInstancesByContributor

Provides list of instances for browsing by contributor

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 500 ] Default: 100 Limit the number of elements returned in the response.
highlightMatch	boolean Default: true Whether to highlight matched resource by query input or not.
precedingRecordsCount	integer [ 1 .. 100 ] Number of preceding records for browsing around and around-including options

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/browseContributorsResult.sample"

browseAuthorities

Provides list of authorities by headingRef

query Parameters

query required	string A CQL query string with search conditions.
limit	integer [ 0 .. 500 ] Default: 100 Limit the number of elements returned in the response.
expandAll	boolean Default: false Whether to return only basic properties or entire instance.
highlightMatch	boolean Default: true Whether to highlight matched resource by query input or not.
precedingRecordsCount	integer [ 1 .. 100 ] Number of preceding records for browsing around and around-including options

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Responses

Response samples

200
400
500

Content type

application/json

"examples/searchResult.sample"

index-management

createIndices

Creates indices for passed resource name and tenant id in request header.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Request Body schema: application/json

resourceName

required

string

Name of resource

Responses

Request samples

Payload

Content type

application/json

"examples/indexRequestBody.sample"

Response samples

200
400
500

Content type

application/json

{"errorMessage": "string",
"indices": ["string"
],
"status": "success"
}

updateMappings

Creates mappings for passed resource name and tenant id in request header.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Request Body schema: application/json

resourceName

required

string

Name of resource

Responses

Request samples

Payload

Content type

application/json

{"resourceName": "string"
}

Response samples

200
500

Content type

application/json

{"errorMessage": "string",
"status": "success"
}

indexRecords

Indexes the records into elasticsearch.

Request Body schema: application/json

Array

id	string Resource id
type	string (resourceEventType) Enum: "UPDATE" "CREATE" "DELETE" "REINDEX" "DELETE_ALL" Resource event operation type - one of [update, create, delete, delete_all, reindex]
deleteEventSubType	string (resourceDeleteEventSubType) Enum: "SOFT_DELETE" "HARD_DELETE" Resource event delete operation type - one of [soft-delete, hard-delete]
tenant	string Tenant id
resourceName	string Name of resource
new	object Instance record new fields
old	object Instance record old fields

Responses

Request samples

Payload

Content type

application/json

"examples/indexRecordRequestBody.sample"

Response samples

200
500

Content type

application/json

"examples/indexRecordResponse.sample"

updateIndexDynamicSettings

Update Index Dynamic Settings data.

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Request Body schema: application/json

resourceName

required

string

Resource name to set index Settings

object (indexDynamicSettings)

Elasticsearch/Opensearch index dynamic settings

numberOfReplicas	integer [ 1 .. 100 ] The number of replicas each primary shard has.
refreshInterval	integer [ -1 .. 3600 ] How often to make new changes to the index visible to search (seconds). '-1' disables refresh.

Responses

Request samples

Payload

Content type

application/json

{"resourceName": "string",
"indexSettings": {"numberOfReplicas": 1,
"refreshInterval": -1
}
}

Response samples

200
500

Content type

application/json

{"errorMessage": "string",
"status": "success"
}

reindexInventoryRecords

Initiates reindex for the inventory records

header Parameters

x-okapi-tenant

required

string

X-Okapi-Tenant header value

Request Body schema: application/json

recreateIndex

boolean

Default: false

Boolean parameter, if set to true - tenant index must be recreated before reindex operation

resourceName

string

Default: "instance"

Resource name to run reindex for

object (indexSettings)

Elasticsearch/Opensearch index settings

numberOfShards	integer [ 1 .. 100 ] The number of primary shards that an index should have.
numberOfReplicas	integer [ 1 .. 100 ] The number of replicas each primary shard has.
refreshInterval	integer [ -1 .. 3600 ] How often to make new changes to the index visible to search (seconds). '-1' disables refresh.

Responses

Request samples

Payload

Content type

application/json

"examples/reindexRequest.sample"

Response samples

200
500

Content type

application/json

{"id": "string",
"jobStatus": "string",
"submittedDate": "string"
}

config

createLanguageConfig

Save languages that will be used for analyzers

Request Body schema: application/json

code required	string[a-zA-Z]{3} An ISO-639-2/B compatible language code.
languageAnalyzer	string Custom elasticsearch analyzer for language.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"languageAnalyzer": "string"
}

Response samples

200
422

Content type

application/json

{"code": "string",
"languageAnalyzer": "string"
}

getAllLanguageConfigs

Get all supported languages

Responses

Response samples

200

Content type

application/json

{"languageConfigs": [{"code": "string",
"languageAnalyzer": "string"
}
],
"totalRecords": 0
}

updateLanguageConfig

Update language config settings

path Parameters

code

required

string[a-zA-Z]{3}

Language code

Request Body schema: application/json

code required	string[a-zA-Z]{3} An ISO-639-2/B compatible language code.
languageAnalyzer	string Custom elasticsearch analyzer for language.

Responses

Request samples

Payload

Content type

application/json

{"code": "string",
"languageAnalyzer": "string"
}

Response samples

200
422

Content type

application/json

{"code": "string",
"languageAnalyzer": "string"
}

deleteLanguageConfig

Delete all supported languages

path Parameters

code

required

string[a-zA-Z]{3}

Language code

Responses

saveFeatureConfiguration

Save feature configuration (enables or disables pre-defined optional search options)

Request Body schema: application/json

feature required	string (tenantConfiguredFeature) Enum: "search.all.fields" "browse.cn.intermediate.values" "browse.cn.intermediate.remove.duplicates" "browse.classifications" The feature name.
enabled required	boolean Action - enable or disable option

Responses

Request samples

Payload

Content type

application/json

{"feature": "search.all.fields",
"enabled": true
}

Response samples

200
400
422

Content type

application/json

{"feature": "search.all.fields",
"enabled": true
}

getAllFeatures

Get all feature configurations per tenant

Responses

Response samples

200

Content type

application/json

{"features": [{"feature": "search.all.fields",
"enabled": true
}
],
"totalRecords": 0
}

updateFeatureConfiguration

Update feature configuration settings

path Parameters

featureId

required

string

Enum: "search.all.fields" "browse.cn.intermediate.values" "browse.cn.intermediate.remove.duplicates" "browse.classifications"

Feature id (name)

Request Body schema: application/json

feature required	string (tenantConfiguredFeature) Enum: "search.all.fields" "browse.cn.intermediate.values" "browse.cn.intermediate.remove.duplicates" "browse.classifications" The feature name.
enabled required	boolean Action - enable or disable option

Responses

Request samples

Payload

Content type

application/json

{"feature": "search.all.fields",
"enabled": true
}

Response samples

200
400
422

Content type

application/json

{"feature": "search.all.fields",
"enabled": true
}

deleteFeatureConfigurationById

Delete feature configuration by id

path Parameters

featureId

required

string

Enum: "search.all.fields" "browse.cn.intermediate.values" "browse.cn.intermediate.remove.duplicates" "browse.classifications"

Feature id (name)

Responses

getBrowseConfigs

Get all configurations for browse type

path Parameters

browseType

required

string (browseType)

Value: "instance-classification"

Browse feature type

Responses

Response samples

200

Content type

application/json

{"configs": [{"id": "all",
"shelvingAlgorithm": "lc",
"typeIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"totalRecords": 0
}

putBrowseConfig

Update configuration for browse type

path Parameters

browseType required	string (browseType) Value: "instance-classification" Browse feature type
browseOptionId required	string (browseOptionType) Enum: "all" "lc" "dewey" Browse option type

Request Body schema: application/json
required

id required	string (browseOptionType) Enum: "all" "lc" "dewey"
shelvingAlgorithm required	string (shelvingOrderAlgorithmType) Enum: "lc" "dewey" "default"
typeIds	Array of strings <uuid> [ items <uuid > ] Type IDs that should be used by the option

Responses

Request samples

Payload

Content type

application/json

{"id": "all",
"shelvingAlgorithm": "lc",
"typeIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

400
422

Content type

application/json

"examples/validationErrorResponse.sample"