Direct API AccessOntology Gateway

Object Service

ObjectService (a.k.a. Ontology Object Service) reads individual ontology objects and searches across them. It is the natural complement to ObjectSetService: object sets define which objects you care about, and ObjectService loads the actual object payloads.

This page covers the endpoints that enable the search, load, and time-filter workflow. Time-filtering happens two ways here: a search filter can range over creation/last-seen timestamps, and history endpoints return an object’s state at a specified version or timestamp.

Base path: /objects

What an ontology object contains

Every OntologyObject returned by this service has the same shape:

  • id (ObjectId) — identifier, unique within its environment.
  • type (ObjectTypeId) — the ontology object type, defined in the active ontology version.
  • environmentId (EnvironmentId) — which environment the object belongs to.
  • metadata (OntologyObjectMetadata) — firstSighting and lastSighting timestamps.
  • properties (list<ObjectProperty>) — typed properties, each with an id, value, origin, and optional trigger indicating the source of the most recent change.
  • links (map<LinkId, list<ObjectId>>) — outgoing links, grouped by link type.
  • tags (set<TagId>) — tags attached to the object.

Endpoints

loadOntologyObject

HTTP: GET /{id}

Fetch a single ontology object by id.

Arguments:

  • id (ObjectId, path) — the object to load.

Returns: OntologyObject — the full object payload.

bulkLoadOntologyObjects

HTTP: POST /bulk

Load multiple ontology objects in one call. Results are paginated. Typically used after ObjectSetService.getObjectSetMembers returns a list of IDs.

Arguments:

  • request (BulkLoadObjectRequest, body) — contains objectIds (list<ObjectId>).
  • pageSize (optional<integer>, query) — number of objects per page.
  • pagingToken (optional<string>, query) — token from a previous response to fetch the next page.

Returns: ObjectPage — contains objects (list<OntologyObject>) and an optional pagingToken for the next page.

searchObjects

HTTP: POST /search

Search for objects matching a filter. The response carries only object ids (with environments) and optionally their outgoing links, not full object payloads — pass the resulting ids to bulkLoadOntologyObjects if you need the full objects.

Filters compose recursively and include time-range predicates over firstSighting and lastSighting, letting you narrow results to a window without first loading every object.

Arguments:

  • request (ObjectSearchRequest, body) — contains:
    • filter (ObjectSearchFilter) — the filter expression.
    • loadLinks (optional<boolean>) — if true, include links from each matched object grouped by link id. Defaults to false.
    • startingSet (optional<ObjectSetId>) — if provided, restrict results to objects already in this set.
  • pageSize (optional<integer>, query) — number of results per page.
  • pagingToken (optional<string>, query) — token from a previous response.

Returns: ObjectIdsAndLinksPage — contains objects (list<OntologyObjectIdsAndLinks>, each with an id, environmentId, and link map) and an optional pagingToken.

getObjectHistory

HTTP: GET /{environmentId}/{id}/history

Get the history of an object between two timestamps. Returns each historical version of the object that existed in the requested window.

Arguments:

  • environmentId (EnvironmentId, path) — the environment containing the object.
  • id (ObjectId, path) — the object to get history for.
  • startTime (datetime, query) — beginning of the history window.
  • endTime (datetime, query) — end of the history window.
  • pageSize (optional<integer>, query) — number of versions per page.
  • pagingToken (optional<string>, query) — token from a previous response.

Returns: ObjectHistoryPage — contains objects (list<OntologyObjectWithVersion>, each pairing a version number with its OntologyObject payload) and an optional pagingToken.

getObjectAtVersion

HTTP: GET /versioned/{environmentId}/{id}

Get an object as it existed at a specific logical version or at a specific timestamp. Exactly one of version or timestamp should be supplied.

Arguments:

  • environmentId (EnvironmentId, path) — the environment containing the object.
  • id (ObjectId, path) — the object to load.
  • version (optional<safelong>, query) — the logical version number to load.
  • timestamp (optional<datetime>, query) — the timestamp at which to read the object.

Returns: OntologyObjectWithVersion — the object’s state at the requested version, with its version number.