Documentation for the API between Pride and Spectrum
When the type of a value is STRING it should not contain any HTML. The client is responsible for escaping HTML entities, so any HTML tags in STRING values will be mangled.
All responses from the server use this basic formatting:
{
'messages': [
// If there are no messages it should be an empty array.
// Each message is formatted like this:
{
'class': 'error' | 'warning' | 'success' | 'info'
// 'error' Something went seriously wrong and either no results were
// produced or the content of this response should be
// considered invalid.
//
// 'warning' There wasn't a serious problem, but the user should be
// notified of a potential issue (upcoming shutdowns, error
// parsing part of the request, etc).
//
// 'success' The request was successful and here are details about what
// the server did.
//
// 'info' A generic notification, probably unrelated to the search
// result, such as libraries closed due to weather or a new
// service is available.
'summary': STRING
// A short summary of what when wrong. Only a couple of sentences.
// Examples: 'Database is not responding' or 'Upcoming shutdown'.
'details': HTML
// A message that can be displayed to the user to give further
// explanation or help. The HTML shouldn't have any attributes applied,
// just basics tags such as <p>, <ol>, <ul>, <strong>, <em>, <etc>.
}
]
'request': OBJECT
// A copy of the object sent to the server to generate this request.
// If no object was sent, this field may be excluded.
'response': ARRAY | OBJECT
// When there is no result of the request or an error occurred the array
// or object should empty.
// Each request type should only be able to return an array or an object,
// not either. Example: datastore queries return an array, while
}In addition to the following more specialized responses, the server must have a URL that which—when hit with a GET request—will return a basic response where the response field is an array containing a datastore object for every single datastore that the server can run queries against.
The basic response formatting is extended with the following when the server is responding to a datastore query (a query for records from a datastore).
{
'total_available': INT | NULL
// How many total records are available for this particular request.
// If NULL it is unknown how many are available.
'datastore': OBJECT
// The object for the datastore that is responding.
// This is sent in the response since it may have new default facet values
// based on the search you just did.
'new_request': OBJECT
// If the client wants to redo the search with a different pagination, they
// should send this version of the request object with modified start and
// count values.
// This is used for things like multisearches, where initially the datastore
// object given was a simplified version, but the datastore object returned
// by the query is more complicated and may use different formatting.
// The 'response' field should contain an array of record objects. See below
// for how those are formatted.
}The basic response formatting is extended with the following when the server is responding to a facet query (a query for more values for a particular facet of a search).
{
// All the usual data ('messages', 'request', etc) is included. See above for
// how this information is organized.
'facet': OBJECT
// The object for the facet the query was done on.
// This is sent in the response since it may have new information based on
// the search you just did.
'total_available': INT | NULL
// How many total values are available for this particular facet.
// If NULL it is unknown how many are available.
// The 'response' field should contain an array of facet value objects. See
// below for how those are formatted.
}Datastore Objects contain all the information necessary to create an interface for a specific search and to generate a query. "Bento box" style searches are represented the same way as any other datastore, but they give multiple URLs to send the query to.
{
'uid': STRING
// A machine readable identifier for this datastore.
// Only contains word characters (letters, numbers, underscores).
'metadata': {
'name': STRING
// A human readable name for the datastore.
'short_desc': STRING
// A single sentence description of what this datastore contains.
}
'url': URL
// The URL where query objects can be sent.
'sorts': ARRAY
// An array containing the various ways the search results can be sorted
// such as alphabetical, by relevance, by date, etc.
// If there are no sorts available, this array should be empty.
// See below for how sort objects are formatted.
'default_sort': STRING
// The 'uid' for the default sort type.
'fields': [
// Array of field objects which look like this:
{
'uid': STRING
// A machine readable identifier for this datastore.
// Only contains word characters (letters, numbers, underscores).
// There should almost always be a field with a 'uid' of 'all_fields'.
// The 'all_fields' is considered the default field which searches
// everything.
'metadata' : {
'name': STRING
// A human readable name for the field.
'short_desc': STRING
// A one to three sentence description of what this field is.
}
'required': BOOLEAN
// Whether or not this field must be set in a query.
'fixed': BOOLEAN
// Whether or not this field can be edited by users.
'default_value': STRING
// The value that this field starts out with.
// Normally this is just set to an empty string.
}
]
'facets': ARRAY
// An array of facet objects. See below for how those are formatted.
'settings': [
// Array of objects which tell you what settings are available on this
// datastore.
{
'uid': STRING
// A machine readable identifier for this particular setting.
'description':
// A human readable description for this setting.
}
]
}Facet objects describe all of the details of a particular facet of a search, give the first set of values for that facet, and give a URL for requesting more values if more are available.
{
'uid': STRING
// A machine readable identifier for this facet.
// Only contains word characters (letters, numbers, underscores).
'metadata' : {
'name': STRING
// A human readable name for the facet.
'short_desc': STRING
// A one to three sentence description of what this facet is.
}
'default_value': ANYTHING
// The value that will be chosen by default if this facet is not set in
// a query.
'default_sort': STRING
// The 'uid' for the default sort type.
'values': ARRAY
// The array contains the first set facet value objects.
// See below for how those are formatted.
'fixed': BOOLEAN
// Whether or not this facet can be edited by users.
'required': BOOLEAN
// Whether or not this field must be set to something other than NULL in
// a query.
'more': URL | false
// If 'more' is set to a URL, there are more facet values. If it is set
// to false then the list of values is complete. A facet value request
// object is sent to this URL to get more values for this facet. See below
// for how those are formatted.
'sorts': ARRAY
// An array containing the various ways the facet values can be sorted
// such as alphabetical, by result count, etc.
// If there are no sorts available, this array should be empty.
// See below for how sort objects are formatted.
}All of the information about a particular possible value for a facet.
{
'value': ANYTHING
// The value that should be sent to the server.
'name': STRING
// A human readable name for this particular value.
'count': INT
// The number of results which have this value.
// If not known, do not create the 'count' key/value pair.
}All of the information about a possible way to sort facet values or records.
{
'uid': STRING
// A machine readable identifier for this sort order.
// Only contains word characters (letters, numbers, underscores).
'metadata': {
'name': STRING
// A human readable name for the sort order.
'short_desc': STRING
// A one to three sentence description of what this sort order is.
}
'group': STRING
// If this sort belongs to a group, provide a machine readable (only
// alphanumeric and underscores) name that will also be applied to every
// other sort object in that group.
// Example: if there is an ascending sort and a descending sort, you create
// one sort object for each and put the same 'group' value in each object.
}Either a complete set of information about one record, or a partial set with a URL which will return the complete set.
{
'type': STRING
// A machine readable 'uid' made out of word characters.
// Identifies the type of record so the client has a hint about
// what fields to expect.
// Examples: 'catalog', 'summon', 'deep_blue'
// Not used to control rendering, nor is it metadata to show
// to the user. It is just to help the client understand what fields
// to expect.
'source': URL
// A URL that returns the complete record for this object.
// This URL can be used as a unique identifier for this record.
'complete': BOOLEAN
// Whether or not there is more info available on this record.
'names': [
// An array of human readable names for this record.
// ALL elements are either HTML or STRING, you can not mix the two.
]
'names_have_html': BOOLEAN
// Whether or not the items in the 'names' array contain HTML.
// Used to determine if those values need to be escaped.
'fields': [
// An array of objects that give the information about this record.
// Each object is formatted as follows:
{
'uid': STRING
// A machine readable identifier for this particular field.
'name':
// A human readable name for this field.
'value': ANYTHING
// Usually this will be a string which is safe to show to users, such as
// a title, but it could be anything.
'value_has_html': BOOLEAN
// Whether or not the name contains HTML.
// Used to determine if it this value needs to be escaped.
}
],
'metadata': OBJECT,
'header': OBJECT
}{
'preview': ARRAY,
'medium': ARRAY,
'full': ARRAY
}{
'term': STRING,
'termPlural': STRING,
'description': ARRAY
}For plain text:
{
'text': STRING
}For an href link:
{
'text': STRING,
'href': STRING
}For a filtered search
{
"text": STRING,
"search": {
"type": STRING,
"scope": STRING,
"value": STRING
}
}For a fielded query search
{
"text": STRING,
"search": {
"type": STRING,
"scope": STRING,
"value": STRING
}
}With icon: Use icon names from Design System Iconography.
{
"text": STRING,
"icon": STRING
}{
}In addition to the following queries, the server has a URL that—when hit with a GET request—gives the client a response containing an array of all the datastores the client can run queries against.
This object represents a query against a specific datastore. The object must be sent via the POST method to the URL specified by the datastore.
{
'uid': STRING
// A machine readable identifier for the datastore you are querying.
'request_id': ANYTHING
// Some data that the server will not modify.
// The 'request' object in the response will have an exact copy of what was
// sent in this field.
// The 'new_request' object in the response will not contain this value
// because the 'new_request' object may not be related to this search such
// as in the case of a multisearch search.
'start': INT
// The index of the item you want to start with. 0 is the first index.
'count': INT
// The number of results you are requesting.
// Note: the server should never send more results than the client
// requested. However, the server may send fewer results than requested.
'field_tree': {} // 4/21/2026: The client should send an empty object for this field.
// Deprecated. But may still be expected by the server.
// A tree that describes the fields being searched, the values to be placed
// into those fields, and how to combine them together.
// An empty object should be sent when not sending any values.
// See below for how this tree is formated
'raw_query': STRING
// A string representing the raw query. Client-side parsing is being
// phased out in favor of server-side parsing. The server-side parser
// is currently (9/28/2022) used for a limited number of datastores.
'facets': OBJECT
// An object which contains the facets that should be applied to the search.
// Each facet is represented as a key/value pair, where the key is the 'uid'
// of the facet as defined by the datastore object, and the value is an
// array of whatever facet values have been selected by the user. The facet
// values can be anything (boolean, string, object, array, number, etc).
'sort': STRING
// The 'uid' for the sort you want to use.
'settings': OBJECT
// An object of additional settings for how you want results formated.
// Each settings should be set as a key/value pair, where the key is the
// 'uid' for that setting and the value is whatever you want to set it to.
}This object represents a request to get more values for a given facet of a specific search. The object must be sent via the POST method to the URL specified by the facet.
{
'uid': STRING;
// The 'uid' for the facet that you are requesting.
'query': OBJECT;
// The datastore query this facet is associated with.
// Should be formatted the same as a datastore query.
'start': INT
// The index of the item you want to start with. 0 is the first index.
'count': INT
// The number of results you are requesting.
// Note: the server should never send more results than the client
// requested. However, the server may send fewer results than requested.
'sort': STRING
// The 'uid' for the sort you want to use.
}Update 4/21/2026: The field tree is no longer submitted client-side. Input validation may still expect it, but an empty object should suffice.
Field trees are represented with a root object which is formatted thusly:
{
'type': 'field_boolean' | 'field' |
'value_boolean' | 'tag' |
'literal' | 'special'
// A 'field_boolean' can have children that are 'field_boolean' or 'field'.
// A 'field' or 'value_boolean' or 'tag' can have children of any type
// except for 'field_boolean' and 'field'.
// A 'literal' or 'special' node can not have any children.
'value': STRING
// In the case of a 'field_boolean' or 'value_boolean' the literal can be:
// 'AND' | 'OR' | 'NOT'
// For 'field' type nodes the value is the 'uid' for the field.
// For 'literal' or 'special' nodes the value is a string, but in the case
// of special nodes the string may have special meaning like it does for *
// For 'tag' nodes the value is a string which assigns a special meaning
// to its children, like the way + and - are used in some searches to say
// that the following is or isn't mandatory.
'children': ARRAY
// The children of this node.
// 'AND' and 'OR' booleans assume that all children are joined with that
// particular boolean.
// 'NOT' booleans assume that all children are joined together with 'AND',
// then that group of nodes has the NOT on it. For example, if the children
// of a 'NOT' are "something", "else" and "blue" then the serialization is:
// NOT("something" AND "else" AND "blue")
}