API docs by Redocly

Search API (v4.1.0)

API for searching, browsing, and managing facets for various record types, including instances, holdings, and authorities. It also provides endpoints for configuring search and browse features, as well as managing the search index.

browse

Provides endpoints to browse records (e.g., instances, authorities) in alphabetical order by a specific field, such as call number, classification number, subject, or contributor.

Browse Instance Call Numbers

Provides list of call numbers

path Parameters
browseOptionId
required
string (browseOptionType)
Enum: "all" "lc" "dewey" "nlm" "sudoc" "other"

Browse option type

query Parameters
query
required
string
Examples:
  • query=number >= "DT571.F84" or number < "DT571.F84" - Search for all classification numbers before and after "DT571.F84"
  • query=number >= "DT571.F84" - Search for all classification numbers after "DT571.F84"
  • query=number >= "DT571.F84" - Search for all classification numbers before "DT571.F84"
  • query=(number >= "DT571.F84" or number < "DT571.F84") and instances.shared==false and instances.locationId=="2b94c631-fca9-4892-a730-03ee529ff6c3" - Search for local classification numbers before and after "DT571.F84"

A CQL query string with filter conditions must include anchor query with range conditions. Anchor field is fullCallNumber. Filters support logic operators AND and OR. All filters should be combined in parentheses. Anchor will be included only if <= or >= are used in the query. Otherwise, the empty row will be added if highlightMatch is equal to true.

Supported filter options
Option Data type Supported operators Description
instances.tenantId string == Filter by tenant ID in consortium
instances.shared boolean == Filter by shared/non-shared in consortium
instances.locationId string == Filter by location ID
callNumberTypeId string == Filter by call-number type ID
limit
integer [ 0 .. 100 ]
Default: 100

Limit the number of elements returned in the browse 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 queries

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "prev": "NS 1 .B4",
  • "next": "NS 1 .B5 suf-1801",
  • "totalRecords": 2
}

Browse Instance Classifications

Provides list of classification numbers

path Parameters
browseOptionId
required
string (browseOptionType)
Enum: "all" "lc" "dewey" "nlm" "sudoc" "other"

Browse option type

query Parameters
query
required
string
Examples:
  • query=number >= "DT571.F84" or number < "DT571.F84" - Search for all classification numbers before and after "DT571.F84"
  • query=number >= "DT571.F84" - Search for all classification numbers after "DT571.F84"
  • query=number >= "DT571.F84" - Search for all classification numbers before "DT571.F84"
  • query=(number >= "DT571.F84" or number < "DT571.F84") and instances.shared==false - Search for local classification numbers before and after "DT571.F84"

A CQL query string with filter conditions must include anchor query with range conditions. Anchor field is number. Filters support logic operators AND and OR. All filters should be combined in parentheses. Anchor will be included only if <= or >= are used in the query. Otherwise, the empty row will be added if highlightMatch is equal to true.

Supported filter options
Option Data type Supported operators Description
instances.tenantId string == Filter by tenant ID in consortium
instances.shared boolean == Filter by shared/non-shared in consortium
limit
integer [ 0 .. 100 ]
Default: 100

Limit the number of elements returned in the browse 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 queries

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "prev": "QA76.73.C15",
  • "items": [
    ]
}

Browse Instance Subjects

Provides list of instances for browsing by subject

query Parameters
query
required
string
Examples:
  • query=value >= "Fantasy" or value < "Fantasy" - Search for all subject values before and after "Fantasy"
  • query=value >= "Fantasy" - Search for all subject values after "Fantasy"
  • query=value >= "Fantasy" - Search for all subject values before "Fantasy"
  • query=(value >= "Fantasy" or value < "Fantasy") and instances.shared==false - Search for local subject values before and after "Fantasy"

A CQL query string with filter conditions must include anchor query with range conditions. Anchor field is value. Filters support logic operators AND and OR. All filters should be combined in parentheses. Anchor will be included only if <= or >= are used in the query. Otherwise, the empty row will be added if highlightMatch is equal to true.

Supported filter options
Option Data type Supported operators Description
typeId uuid == Filter by subject type
sourceId uuid == Filter by subject source
instances.tenantId string == Filter by tenant ID in consortium
instances.shared boolean == Filter by shared/non-shared in consortium
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 queries

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 10,
  • "prev": "Biology",
  • "next": "Physics",
  • "items": [
    ]
}

Browse Instance Contributors

Provides list of instances for browsing by contributor

query Parameters
query
required
string
Examples:
  • query=name >= "Abedi, Ali" or name < "Abedi, Ali" - Search for all contributor values before and after "Abedi, Ali"
  • query=name >= "Abedi, Ali" - Search for all contributor values after "Abedi, Ali"
  • query=name >= "Abedi, Ali" - Search for all contributor values before "Abedi, Ali"
  • query=(name >= "Abedi, Ali" or name < "Abedi, Ali") and instances.shared==false and contributorNameTypeId="b6993450-25c1-4c23-a1d1-98abb67fb506" - Search for local contributor values with name type id = "b6993450-25c1-4c23-a1d1-98abb67fb506" before and after "Abedi, Ali"

A CQL query string with filter conditions must include anchor query with range conditions. Anchor field is name. Filters support logic operators AND and OR. All filters should be combined in parentheses. Anchor will be included only if <= or >= are used in the query. Otherwise, the empty row will be added if highlightMatch is equal to true.

Supported filter options
Option Data type Supported operators Description
contributorNameTypeId uuid == Filter by contributor name type
instances.tenantId string == Filter by tenant ID in consortium
instances.shared boolean == Filter by shared/non-shared in consortium
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 queries

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 5,
  • "next": "Paul McCartney",
  • "items": [
    ]
}

Browse Authorities

Provides list of authorities by headingRef

query Parameters
query
required
string
Examples:
  • query=headingRef >= "Comic-Con" or headingRef < "Comic-Con" - Search for all authority headings before and after "Comic-Con"
  • query=headingRef >= "Comic-Con" - Search for all authority headings after "Comic-Con"
  • query=headingRef >= "Comic-Con" - Search for all authority headings before "Comic-Con"
  • query=(headingRef >= "Comic-Con" or headingRef < "Comic-Con") and authRefType==("Authorized" or "Auth/Ref") and headingType=="Personal Name" - Search for "Authorized" or "Auth/Ref" personal name authority headings before and after "Comic-Con"

A CQL query string with filter conditions must include anchor query with range conditions. Anchor field is headingRef. Filters support logic operators AND and OR. All filters should be combined in parentheses. Anchor will be included only if <= or >= are used in the query. Otherwise, the empty row will be added if highlightMatch is equal to true.

Supported filter options
Option Data type Supported operators Description
tenantId string == Filter by tenant ID in consortium
shared boolean == Filter by shared/non-shared in consortium
sourceFileId uuid == Filter by authority source file ID. `NULL` value to filter by non-specified.
headingType string == Filter by heading type: `Personal Name`, `Corporate Name`, `Conference Name`, `Geographic Name`, `Uniform Title`, `Topical`, `Genre`
isTitleHeadingRef boolean == Filter title/non-title heading
authRefType boolean == Filter by reference type: `Authorized`, `Reference`, `Auth/Ref`
subjectHeadings char == Filter by subject heading code
metadata.createdDate date ==, >, <, <=, >= Filter by authority create date
metadata.updatedDate date ==, >, <, <=, >= Filter by authority update date
expandAll
boolean
Default: false

Whether to return only basic properties or entire authority record.
Basic fields are:

  • id
  • tenantId
  • shared
  • headingType
  • authRefType
  • headingRef
  • sourceFileId
  • naturalId
  • numberOfTitles
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 queries

limit
integer [ 0 .. 500 ]
Default: 100

Limit the number of elements returned in the response.

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
Example
{
  • "totalRecords": 3,
  • "prev": "Adair, Thomas Montgomery, 1913-1988",
  • "next": "Leven, Mel",
  • "items": [
    ]
}

config

Provides endpoints to configure search and browse features, such as enabling/disabling specific features or managing language settings.

Get Language Configurations

Get all supported languages

Responses

Response samples

Content type
application/json
{
  • "languageConfigs": [
    ],
  • "totalRecords": 2
}

Create Language Configuration

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

Content type
application/json
{
  • "code": "eng",
  • "languageAnalyzer": "eng-analyzer"
}

Response samples

Content type
application/json
{
  • "code": "eng",
  • "languageAnalyzer": "eng-analyzer"
}

Delete Language Configuration

Delete all supported languages

path Parameters
code
required
string[a-zA-Z]{3}

Language code

Responses

Update Language Configuration

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

Content type
application/json
{
  • "code": "eng",
  • "languageAnalyzer": "eng-analyzer"
}

Response samples

Content type
application/json
{
  • "code": "eng",
  • "languageAnalyzer": "eng-analyzer"
}

Get Feature Configurations

Get all feature configurations per tenant

Responses

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "totalRecords": 1
}

Save Feature Configuration

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.contributors" "browse.subjects" "browse.classifications" "browse.call-numbers"

The feature name.

enabled
required
boolean

Action - enable or disable option

Responses

Request samples

Content type
application/json
{
  • "feature": "search.all.fields",
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "feature": "search.all.fields",
  • "enabled": false
}

Delete Feature Configuration

Delete feature configuration by id

path Parameters
featureId
required
string
Enum: "search.all.fields" "browse.contributors" "browse.subjects" "browse.classifications" "browse.call-numbers"

Feature id (name)

Responses

Update Feature Configuration

Update feature configuration settings

path Parameters
featureId
required
string
Enum: "search.all.fields" "browse.contributors" "browse.subjects" "browse.classifications" "browse.call-numbers"

Feature id (name)

Request Body schema: application/json
feature
required
string (tenantConfiguredFeature)
Enum: "search.all.fields" "browse.contributors" "browse.subjects" "browse.classifications" "browse.call-numbers"

The feature name.

enabled
required
boolean

Action - enable or disable option

Responses

Request samples

Content type
application/json
{
  • "feature": "search.all.fields",
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "feature": "search.all.fields",
  • "enabled": false
}

Get Browse Configurations

Get all configurations for browse type

path Parameters
browseType
required
string (browseType)
Enum: "instance-classification" "instance-call-number"

Browse feature type

Responses

Response samples

Content type
application/json
{
  • "configs": [
    ],
  • "totalRecords": 3
}

Update Browse Configurations

Update configuration for browse type

path Parameters
browseType
required
string (browseType)
Enum: "instance-classification" "instance-call-number"

Browse feature type

browseOptionId
required
string (browseOptionType)
Enum: "all" "lc" "dewey" "nlm" "sudoc" "other"

Browse option type

Request Body schema: application/json
required
id
required
string (browseOptionType)
Enum: "all" "lc" "dewey" "nlm" "sudoc" "other"

Browse option type

shelvingAlgorithm
required
string (shelvingOrderAlgorithmType)
Enum: "lc" "dewey" "nlm" "sudoc" "default"

Shelving order algorithm

typeIds
Array of strings <uuid> [ items <uuid > ]

Type IDs that should be used by the option

Responses

Request samples

Content type
application/json
{
  • "id": "all",
  • "shelvingAlgorithm": "default",
  • "typeIds": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 1
}

facets

Provides endpoints to retrieve aggregated information (facets) about records, such as counts of records by specific fields or ranges of values. This can be used for faceted search or browsing.

Get Facets

Provides list of facets for the record type

path Parameters
recordType
required
string (recordType)
Enum: "instances" "authorities" "contributors" "subjects" "classifications" "call-numbers"

Type of record to get facets for.

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

Content type
application/json
{
  • "facets": {
    },
  • "totalRecords": 1
}

index-management

Provides endpoints to manage the search index, including creating or updating mappings, settings, and manually populating the index with records from external sources (e.g., inventory).

Create Index

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

Content type
application/json
{
  • "resourceName": "instance"
}

Response samples

Content type
application/json
{
  • "errorMessage": "Failed to update index settings",
  • "status": "error"
}

Create Index Mappings

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

Content type
application/json
{
  • "resourceName": "authority"
}

Response samples

Content type
application/json
{
  • "errorMessage": "Failed to update index settings",
  • "status": "error"
}

Index Records

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "status": "success"
}

Update Index Settings

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 [ 0 .. 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

Content type
application/json
{
  • "resourceName": "instance",
  • "indexSettings": {
    }
}

Response samples

Content type
application/json
{
  • "errorMessage": "Failed to update index settings",
  • "status": "error"
}

Re-Index

Initiates reindex for the inventory records

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Request Body schema: application/json
required
recreateIndex
boolean
Default: false

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

resourceName
required
string
Enum: "authority" "location" "linked-data-instance" "linked-data-work" "linked-data-hub"

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 [ 0 .. 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

Content type
application/json
{
  • "recreateIndex": true,
  • "resourceName": "authority"
}

Response samples

Content type
application/json
{
  • "id": "68ec4438-8b93-46df-8c36-232db4f7862e",
  • "jobStatus": "In progress",
  • "submittedDate": "2024-12-05T10:22:22"
}

Get Reindex Status

Get a list of statuses for each resource reindexing

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Re-Index

Initiates the full reindex for the inventory instance records

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Request Body schema: application/json
numberOfShards
integer [ 1 .. 100 ]

The number of primary shards that an index should have.

numberOfReplicas
integer [ 0 .. 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

Content type
application/json
{
  • "numberOfShards": 1,
  • "numberOfReplicas": 1,
  • "refreshInterval": 1
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 1
}

Upload Re-Index

Initiates reindex upload for inventory instance records

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Request Body schema: application/json
entityTypes
required
Array of objects non-empty
Items Enum: "instance" "subject" "contributor" "classification" "call-number"

Entity name to run reindex upload

object (indexSettings)

Elasticsearch/Opensearch index settings

numberOfShards
integer [ 1 .. 100 ]

The number of primary shards that an index should have.

numberOfReplicas
integer [ 0 .. 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

Content type
application/json
{
  • "entityTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 1
}

Failed Merge Ranges Re-Index

Initiates reindexing of failed merge ranges for inventory instance records

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_records": 1
}

search

Provides endpoints to search for records (e.g., instances, authorities) using CQL (Contextual Query Language) queries. Supports various search options and retrieval of search results.

Search Instances

Get a list of instances for CQL query

query Parameters
query
required
string

A CQL query string

Instance search options
Option Type Example Description
keyword full-text keyword all "web semantic" An alias for: title, alternativeTitles, indexTitle, series, identifiers.value, contributors.name
id term id=="1234567" Matches instance with the id
hrid term hrid=="hr1*0" Matches instances with given HRID
source term source=="MARC" Matches instances with given source (FOLIO/MARC)
title full-text title all "semantic web" Matches instances with the given title, searches against title, alternativeTitles, indexTitle, series fields
alternativeTitles.alternativeTitle full-text alternativeTitles.alternativeTitle all "semantic web" Matches instances with the given alternative title
uniformTitle full-text uniformTitle all "semantic web" Matches instances with the given uniform title
indexTitle full-text indexTitle all "semantic web" Matches instances with the given index title
series full-text series all "series" Matches instance with given series value
identifiers.value term identifiers.value = "1023*" Matches instances with the given identifier value
identifiers.identifierTypeId term identifiers.identifierTypeId=="123" identifiers.value = "1023*" Matches instances that have an identifier of type 123 and ANY identifier with value 1023*
contributors full-text contributors all "John" Matches instances that have a John contributor
contributors.name term contributors.name all "John" Matches instances that have a primary John contributor
contributors.contributorTypeId term contributors.contributorTypeId all "1234567" Matches instances that have a contributor type Id 1234567
contributors.contributorNameTypeId term contributors.contributorNameTypeId all "1234567" Matches instances that have a contributor name type Id 1234567
contributors.primary term contributors all "John" and contributors.primary==true Matches instances that have a primary John contributor
contributors.authorityId term contributors.authorityId == "81ae0f60-f2bc-450c-84c8-5a21096daed9" Matches instances that have a contributor authorityId 81ae0f60-f2bc-450c-84c8-5a21096daed9
authorityId term authorityId == "81ae0f60-f2bc-450c-84c8-5a21096daed9" Matches instances that have a contributor authorityId 81ae0f60-f2bc-450c-84c8-5a21096daed9
subjects full-text subjects all "Chemistry" Matches instances that have a Chemistry subject
instanceTypeId term instanceTypeId == "123" Matches instances with the 123 type
statusId term statusId == "123" Matches instances with the 123 status
instanceFormatIds term instanceFormatIds == "123" Matches instances with the 123 format id
languages term languages == "eng" Matches instances that have eng language
metadata.createdDate term metadata.createdDate > "2021-03-01T00:00:00.000+00:00" Matches instances that were created after 2020-12-12
metadata.updatedDate term metadata.updatedDate > "2020-12-12" Matches instances that were updated after 2020-12-12
modeOfIssuanceId term modeOfIssuanceId=="123" Matches instances that have 123 mode of issuance
natureOfContentTermIds term natureOfContentTermIds=="123" Matches instances that have 123 nature of content
publisher full-text publisher all "Publisher of Ukraine" Matches instances that have Publisher of Ukraine publisher
publication.place full-text publication.place all "Ukraine" Matches instances that have `Ukraine` in publication place
instanceTags term instanceTags=="important" Matches instances that have important tag
classifications.classificationNumber term classifications.classificationNumber=="cl1" Matches instances that have cl1 classification number
classifications.classificationTypeId term classifications.classificationTypeId == "123" Matches instances that have classification type id 123
electronicAccess full-text electronicAccess any "resource" An alias for electronicAccess fields - uri, linkText, publicNote
electronicAccess.uri term electronicAccess.uri="http://folio.org*" Search by electronic access URI
electronicAccess.linkText full-text electronicAccess.linkText="Folio website" Search by electronic access link text
electronicAccess.publicNote full-text electronicAccess.publicNote="a rare book" Search by electronic access public note
electronicAccess.relationshipId term electronicAccess.relationshipId="47d563ed-1ae2-41dc-97f8-8ebefce904f0" Search by electronic access relationship type ID
staffSuppress term staffSuppress==true Matches instances that are staff suppressed
discoverySuppress term discoverySuppress==true Matches instances that are suppressed from discovery
publicNotes full-text publicNotes all "public note" Matches instances that have a public note (i.e. note.staffOnly is false)
administrativeNotes full-text administrativeNotes all "librarian note" Search by administrative notes
notes.note full-text notes.note all "librarian note" Search by instance notes (include staffOnly)
isbn term isbn="1234*" Matches instances that have an ISBN identifier with the given value
issn term issn="1234*" Matches instances that have an ISSN identifier with the given value
oclc term oclc="1234*" Matches instances that have an OCLC identifier with the given value
lccn term lccn = "LCCN" Matches instances with the given lccn
normalizedClassificationNumber term normalizedClassificationNumber == "LCCN" Matches instances with the given classification number (normalizes case, whitespaces, special characters, supports leading and trailing wildcard)
normalizedDate1 term normalizedDate1>=1990 Matches instances with the given Date1 (normalizes alpha u characters)
classificationId term classificationId = "c4f60d7413158e9466856f4c0250d91d312f86cf" Matches instances with the given classificationId
Holdings search options
Option Type Example Description
holdings.id term holdings.id=="1234567" Matches instances that have a holding with the id
holdings.sourceId term holdings.sourceId=="FOLIO" Matches instances that have a holding with the source FOLIO
holdings.holdingsTypeId term holdings.holdingsTypeId=="1234567" Matches instances that have a holding with the holdings type id 1234567
holdings.permanentLocationId term holdings.permanentLocationId=="123765" Matches instances that have holdings with given statisticalCodeId
holdings.statisticalCodeIds term holdings.statisticalCodeIds=="123765" Matches instances that have holdings with given permanentLocationId
holdings.discoverySuppress term holdings.discoverySuppress==true Matches instances that have holdings suppressed/not suppressed from discovery
holdings.hrid term holdings.hrid=="hr10*3" Matches instances that have a holding with given HRID
holdingsTags term holdingsTags=="important" Matches instances that have holdings with given tags
holdingsFullCallNumbers term holdingsFullCallNumbers="cn*434" Matches instances that have holdings with given call number string (prefix + call number + suffix)
holdingsNormalizedCallNumbers term holdingsNormalizedCallNumbers="cn434" Matches instances that have holdings with given call number and might not be formatted correctly
holdings.electronicAccess full-text holdings.electronicAccess any "resource" An alias for electronicAccess fields - uri, linkText, publicNote
holdings.electronicAccess.uri term holdings.electronicAccess.uri="http://folio.org*" Search by electronic access URI
holdings.electronicAccess.linkText full-text holdings.electronicAccess.linkText="Folio website" Search by electronic access link text
holdings.electronicAccess.publicNote full-text holdings.electronicAccess.publicNote="a rare book" Search by electronic access public note
holdings.electronicAccess.relationshipId term holdings.electronicAccess.relationshipId="0b460e53-aee9-41a8-a447-0755cdac22ca" Search by holdings electronic access relationship type ID
holdings.administrativeNotes full-text holdings.administrativeNotes all "librarian note" Search by holdings administrative notes
holdings.notes.note full-text holdings.notes.note all "librarian note" Search by holdings notes
holdingsTypeId term holdingsTypeId=="123" Search by holdings type id
holdingsPublicNotes full-text holdingsPublicNotes all "public note" Search by holdings public notes
holdingsIdentifiers term holdingsIdentifiers == "ho00000000006" Search by holdings Identifiers: holdings.id, holdings.hrid, holdings.formerIds
holdings.metadata.createdDate term metadata.createdDate > "2020-12-12" Matches instances with holdings that were created after 2020-12-12
holdings.metadata.updatedDate term metadata.updatedDate > "2020-12-12" Matches instances with holdings that were updated after 2020-12-12
Item search options
Option Type Example Description
item.id term item.id=="1234567" Matches instances that have an item with the id
item.hrid term item.hrid=="it001" Matches instances that have an item with the HRID
item.barcode term item.barcode=="10011" Matches instances that have an item with the barcode
item.effectiveLocationId term item.effectiveLocationId=="1212" Matches instances that have item with the effective location
item.statisticalCodeIds term item.statisticalCodeIds=="1212" Matches instances that have item with the statistical code Id
item.status.name term item.status.name=="Available" Matches instances that have item with given status
item.materialTypeId term item.materialTypeId="23434" Matches instances that have item with given material type
item.discoverySuppress term item.discoverySuppress=true Matches instances that have item suppressed/not suppressed from discovery
itemFullCallNumbers term itemFullCallNumbers="cn*434" Matches instances that have item with given call number string (prefix + call number + suffix)
itemNormalizedCallNumbers term itemNormalizedCallNumbers="cn434" Matches instances that have item with given call number and might not be formatted correctly
itemLevelCallNumberTypeId term itemLevelCallNumberTypeId="81ae0f60-f2bc-450c-84c8-5a21096daed9" Matches instances that have item with given call number type id
itemTags term itemTags="important" Matches instances that have item with given tag
item.electronicAccess full-text item.electronicAccess any "resource" An alias for electronicAccess fields - uri, linkText, publicNote
item.electronicAccess.uri term item.electronicAccess.uri="http://folio.org*" Search by electronic access URI
item.electronicAccess.linkText full-text item.electronicAccess.linkText="Folio website" Search by electronic access link text
item.electronicAccess.publicNote full-text item.electronicAccess.publicNote="a rare book" Search by electronic access public note
item.electronicAccess.relationshipId term item.electronicAccess.relationshipId="0b460e53-aee9-41a8-a447-0755cdac22ca" Search by item electronic access relationship type ID
item.administrativeNotes full-text item.administrativeNotes all "librarian note" Search by item administrative notes
item.notes.note full-text item.notes.note all "librarian note" Search by item notes and circulation notes
item.circulationNotes.note full-text item.circulationNotes.note all "circulation note" Search by item circulation notes
itemPublicNotes full-text itemPublicNotes all "public note" Search by item public notes and circulation notes
itemIdentifiers term itemIdentifiers all "81ae0f60-f2bc-450c-84c8-5a21096daed9" Search by item Identifiers: item.id, item.hrid, item.formerIds, item.accessionNumber, item.itemIdentifier
item.metadata.createdDate term item.metadata.createdDate > "2020-12-12" Matches instances with item that were created after 2020-12-12
item.metadata.updatedDate term item.metadata.updatedDate > "2020-12-12" Matches instances with item that were updated after 2020-12-12
callNumberType term callNumberType = "lc" Matches instances with item that has call number with type Library of Congress classification. Supported values: lc, dewey, nlm, sudoc, other, local.
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

Content type
application/json
{
  • "instances": [
    ],
  • "totalRecords": 1
}

Search Authorities

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

Content type
application/json
{
  • "totalRecords": 10,
  • "authorities": [
    ]
}

Search Linked Data Works

Get a list of linked data records for CQL query

query Parameters
query
required
string

A CQL query string with search conditions.

limit
integer [ 0 .. 100 ]
Default: 10

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.

omitInstances
boolean
Default: false

Whether to omit instances from a Work search result set

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "searchQuery": "query string",
  • "content": [
    ],
  • "pageNumber": 0,
  • "totalPages": 10,
  • "totalRecords": 100
}

Search Linked Data Hubs

Get a list of linked data Hubs records for CQL query

query Parameters
query
required
string

A CQL query string with search conditions.

limit
integer [ 0 .. 100 ]
Default: 10

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.

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "searchQuery": "query string",
  • "content": [
    ],
  • "pageNumber": 0,
  • "totalPages": 3,
  • "totalRecords": 27
}

Search Linked Data Instances

Get a list of linked data records for CQL query

query Parameters
query
required
string

A CQL query string with search conditions.

limit
integer [ 0 .. 100 ]
Default: 10

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.

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "searchQuery": "query string",
  • "content": [
    ],
  • "pageNumber": 0,
  • "totalPages": 10,
  • "totalRecords": 100
}

search-consortium

Provides endpoints to search for consolidated records (e.g., holdings, items) across multiple institutions or libraries within a consortium.

Get Consolidated Holdings

Get a list of holdings (only for consortium environment)

query Parameters
instanceId
string

UUID of the instance

tenantId
string

Tenant ID to filter by

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
  • 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

Content type
application/json
{
  • "holdings": [
    ],
  • "totalRecords": 1203
}

Get Consolidated Items

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 to filter by

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

Content type
application/json
{
  • "items": [
    ],
  • "totalRecords": 1203
}

Get Consortium Locations

Get a list of locations (only for consortium environment)

query Parameters
tenantId
string

Tenant ID to filter by

id
string

ID to filter by

limit
integer [ 0 .. 10000 ]
Default: 10000

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
Default: "name"

Defines a field to sort by. Possible values:

  • id
  • tenantId
  • name
sortOrder
string (sortOrder)
Enum: "asc" "desc"

Defines sorting order

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 0,
  • "locations": [
    ]
}

Get Consortium Campuses

Get a list of campuses (only for consortium environment)

query Parameters
tenantId
string

Tenant ID to filter by

id
string

ID to filter by

limit
integer [ 0 .. 1000 ]
Default: 1000

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
Default: "name"

Defines a field to sort by. Possible values:

  • id
  • tenantId
  • institutionId
  • name
sortOrder
string (sortOrder)
Enum: "asc" "desc"

Defines sorting order

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 0,
  • "campuses": [
    ]
}

Get Consortium Libraries

Get a list of libraries (only for consortium environment)

query Parameters
tenantId
string

Tenant ID to filter by

id
string

ID to filter by

limit
integer [ 0 .. 1000 ]
Default: 1000

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
Default: "name"

Defines a field to sort by. Possible values:

  • id
  • tenantId
  • campusId
  • name
sortOrder
string (sortOrder)
Enum: "asc" "desc"

Defines sorting order

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 0,
  • "libraries": [
    ]
}

Get Consortium Institutions

Get a list of institutions (only for consortium environment)

query Parameters
tenantId
string

Tenant ID to filter by

id
string

ID to filter by

limit
integer [ 0 .. 1000 ]
Default: 1000

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
Default: "name"

Defines a field to sort by. Possible values:

  • id
  • tenantId
  • name
sortOrder
string (sortOrder)
Enum: "asc" "desc"

Defines sorting order

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "institutions": [
    ],
  • "totalRecords": 0
}

Fetch Consolidated Items

Fetch a list of items (only for consortium environment)

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Request Body schema: application/json
identifierType
required
string
Enum: "id" "hrid" "accessionNumber" "formerIds" "barcode" "holdingsRecordId" "instanceId" "instanceHrid" "itemBarcode"

Type of entity identifier

identifierValues
required
Array of strings

Entity identifier values

Responses

Request samples

Content type
application/json
{
  • "identifierType": "id",
  • "identifierValues": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalRecords": 1203
}

Fetch Consolidated Holdings

Fetch a list of holdings (only for consortium environment)

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Request Body schema: application/json
identifierType
required
string
Enum: "id" "hrid" "accessionNumber" "formerIds" "barcode" "holdingsRecordId" "instanceId" "instanceHrid" "itemBarcode"

Type of entity identifier

identifierValues
required
Array of strings

Entity identifier values

Responses

Request samples

Content type
application/json
{
  • "identifierType": "id",
  • "identifierValues": [
    ]
}

Response samples

Content type
application/json
{
  • "holdings": [
    ],
  • "totalRecords": 1203
}

Fetch consolidated holding by id

Get holding by id (only for consortium environment)

path Parameters
id
required
string <uuid>

The UUID of a record

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "callNumberPrefix": "callNumberPrefix",
  • "instanceId": "instanceId",
  • "discoverySuppress": true,
  • "hrid": "hrid",
  • "callNumber": "callNumber",
  • "permanentLocationId": "permanentLocationId",
  • "tenantId": "tenantId",
  • "copyNumber": "copyNumber",
  • "callNumberSuffix": "callNumberSuffix",
  • "id": "id"
}

Fetch consolidated item by id

Get an item (only for consortium environment)

path Parameters
id
required
string <uuid>

The UUID of a record

header Parameters
x-okapi-tenant
required
string

X-Okapi-Tenant header value

Responses

Response samples

Content type
application/json
{
  • "instanceId": "instanceId",
  • "hrid": "hrid",
  • "tenantId": "tenantId",
  • "id": "id",
  • "holdingsRecordId": "holdingsRecordId",
  • "barcode": "barcode"
}

search-resources-ids

Provides endpoints to retrieve record IDs by CQL queries, without returning the full record data.

Get Job

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

Content type
application/json
{
  • "id": "eea1432c-beb8-4f4f-b96a-f8de977f1106",
  • "query": "title=*",
  • "status": "COMPLETED",
  • "entityType": "INSTANCE",
  • "createdDate": "1974-12-03T00:00:00"
}

Trigger new Job

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
required
query
required
string

CQL query for getting ids.

entityType
required
string
Enum: "INSTANCE" "AUTHORITY" "HOLDINGS"

Type of entity for streaming ids.

Responses

Request samples

Content type
application/json
{
  • "query": "title=*",
  • "entityType": "INSTANCE"
}

Response samples

Content type
application/json
{
  • "id": "eea1432c-beb8-4f4f-b96a-f8de977f1106",
  • "query": "title=*",
  • "status": "COMPLETED",
  • "entityType": "INSTANCE",
  • "createdDate": "1974-12-03T00:00:00"
}

Get Resource IDs

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

Content type
application/json
{
  • "ids": [
    ],
  • "totalRecords": 3
}