API Reference

API search parameters

You can filter a search and control its output by passing search parameters in the $data argument (PHP API) or in the URL query string (REST API).

Common parameters

These are the search parameters that are common to almost all API resources:

Parameter Description Type Default
id Limit matches to the given ID or IDs. Multiple IDs can be specified using the PHP array syntax (id[]). (added in 3.0.0) integer or integer[] none
sort_by Sort the result set by this field string created
sort_order Sort the result set in this order, ascending ("asc") or descending ("desc") string desc
page The page number of the result set to return integer 1
per_page The number of results per page integer uses global "results per page" setting
limit The number of results to return integer 0 (all)
offset The number offset of results to return integer 0 (no offset)

Parameters for RDF resources

These are the search parameters that are common to all RDF resources (items, media, item_sets):

Parameter Description Type
fulltext_search Get RDF resources where there's a match in the fulltext index string
search Get RDF resources where there's an exact match in a value string
owner_id Get RDF resources that belong to this owner integer
resource_class_label Get RDF resources with a class that has this unique label string
resource_class_id Get RDF resources with a class that has this unique identifier integer
resource_template_id Get RDF resources with a template that has this unique identifier integer
is_public Get RDF resources that are public OR private boolean

RDF resources also feature a fine-grained value search using the parameter key property and this query format:

  • property[{index}][joiner]: Boolean joiner with previous query (valid options are and, or; default is and)
  • property[{index}][property]: property ID or term name (e.g., dcterms:title)
    • You can also provide 0 as the property ID here to search across all values regardless of property
  • property[{index}][text]: search text
  • property[{index}][type]: search type
    • eq: is exactly
    • in: contains
    • sw: starts with
    • ew: ends with
    • res: links to the Omeka S resource with the given ID
    • ex: has any value (this search type does not require passing text)
    • All the types can be negated by prefixing them with the letter n. So, neq will return resources that do not have a value that exactly matches the search text.

Parameters for items

Parameter Description Type
item_set_id Get items assigned to this item set. Pass an array of IDs (PHP-style) to return items in any one of the given sets. integer (or array of integers)
site_id Get items in this site's item pool integer
site_attachments_only When using site_id, whether items must be attached to a site page block bool

Parameters for media

Parameter Description Type
item_id Get media assigned to this item integer
media_type Get media of this media type string
site_id Get media in this site's item pool AND are attached to a block integer
ingester Get media using this ingester (added in 3.0.0) string
renderer Get media using this renderer (added in 3.0.0) string

Parameters for item_sets

Parameter Description Type
is_open Get item sets that are open or closed bool
site_id Get item sets in this site's item set pool integer

Parameters for vocabularies

Parameter Description Type
owner_id Get vocabularies belonging to this owner integer
namespace_uri Get a vocabulary that has this unique namespace URI (e.g. "http://purl.org/dc/terms/") string
prefix Get a vocabulary that has this unique namespace prefix (e.g. "dcterms") string

Parameters for resource_classes

Parameter Description Type
owner_id Get classes that belong to this owner integer
vocabulary_id Get classes that belong to a vocabulary that has this unique identifier integer
vocabulary_namespace_uri Get classes that belong to a vocabulary that has this unique namespace URI (e.g. "http://purl.org/dc/dcmitype/") string
vocabulary_prefix Get classes that belong to a vocabulary that has this unique namespace prefix (e.g. "dcmitype") string
local_name Get classes with this local name (e.g. "Image") string
term Get a class with this unique term (e.g. "dcmitype:Image") string
used Only get classes used by at least one resource (added in 3.0.0) boolean

Parameters for properties

Parameter Description Type
owner_id Get properties that belong to this owner integer
vocabulary_id Get properties that belong to a vocabulary that has this unique identifier integer
vocabulary_namespace_uri Get properties that belong to a vocabulary that has this unique namespace URI (e.g. "http://purl.org/dc/terms/") string
vocabulary_prefix Get properties that belong to a vocabulary that has this unique namespace prefix (e.g. "dcterms") string
local_name Get properties with this local name (e.g. "title") string
term Get a property with this unique term (e.g. "dcterms:title") string
used Only get classes used by at least one resource (added in 3.0.0) boolean

Parameters for users

Parameter Description Type
email Get a user that has this unique email string
name Get users that have this name string
role Get users that have this role (choices are: global_admin, site_admin, editor, reviewer, author, researcher) string
is_active Get users that are active or inactive bool
site_permission_site_id Get users that have site permissions integer

API request options

For most resources, you can pass options that affect the execution of a request in the $options argument. These options are only available when using the PHP API, and are not available in the REST API.

Option Type Description Default
initialize bool Set whether to initialize the request during execute() (e.g. trigger API-pre events). true
finalize bool Set whether to finalize the request during execute() (e.g. trigger API-post events and transform response content according to the "responseContent" option). true
returnScalar string Set which field/column to return as an array of scalars during a SEARCH request. The request will not finalize when this option is set. false
isPartial bool Set whether this is a partial UPDATE request (aka PATCH). false
collectionAction string Set which action to take on certain collections during a partial UPDATE request:
  • "replace": the passed data replaces the collection
  • "append": append passed data to collections
  • "remove": remove passed data from collections
 "replace"
continueOnError bool Set whether a BATCH_CREATE operation should continue processing on error. false
flushEntityManager bool Set whether to flush the entity manager during CREATE, UPDATE, and DELETE. true
responseContent string Set the type of content the API response should contain. Default is "representation". The types are:
  • "representation": an API resource representation
  • "reference": an API resource reference
  • "resource": an API resource
 "representation"