Portal Search: REST API Reference

Author: @Bryan Fauble

Overview

Portal Search provides REST endpoints for creating OpenSearch-backed search indexes over Synapse table-like entities and executing full-text search queries against them.

Resources

The API is organized around four standalone configuration resources under /repo/v1/search/* and one SearchIndex Synapse Entity managed via the standard entity controller under /repo/v1/entity/*.

All resources are logically scoped to an Organization (an existing Synapse concept — CRUD and ACL management at /schema/organizations/*), but note that SearchIndex does not have its own organizationId field; it is scoped via the standard entity parentId (Project or Folder).

Resources compose as:

SearchIndex → SearchConfiguration → {SynonymSets[], ColumnAnalyzerOverrides[]}.

TextAnalyzer is a standalone resource referenced by ColumnAnalyzerOverrideEntry.indexAnalyzerId/searchAnalyzerId and SearchConfiguration.defaultAnalyzerId.

Design Principles

• Organization-scoped authorization for configuration. The four configuration resources (SynonymSet, ColumnAnalyzerOverride, TextAnalyzer, SearchConfiguration) are Organization-scoped and identified by organizationId. They are publicly readable; mutations require Organization ACL permissions. SearchIndex is a standard Synapse Entity without its own organizationId field; it is scoped by parentId (Project or Folder), and its ACL follows normal entity rules.

• Secure search access. Search queries and autocomplete requests are not fully public. Callers must have:

  • READ on the SearchIndex entity and

  • Sufficient permissions to read from the underlying table referenced by definingSQL (mirrors the MaterializedView authorization pattern).

• Build-once semantics with rebuild on update. AOSS indexes are point-in-time snapshots. There are no incremental updates. The lifecycle worker builds (or rebuilds) indexes on both CREATE and UPDATE of SearchIndex entities.

• Single-entity constraint. definingSQL must reference exactly one entity. Multi-entity JOINs are rejected with 400 Bad Request.

• Shared resource protection. SynonymSets and ColumnAnalyzerOverrides cannot be deleted while referenced by any SearchConfiguration.

• Name uniqueness.

  • For SynonymSet, ColumnAnalyzerOverride, and SearchConfiguration, names are unique per Organization: UNIQUE(organizationId, name).

  • For TextAnalyzer, system analyzer names are globally unique; user-defined analyzer names are unique per Organization.

  • For SearchIndex (as a Synapse Entity), name uniqueness follows the standard entity rules: unique within its parent container (parentId).

• Single polling point. Search queries run as async jobs. If an index is still building, the worker automatically retries — the client only polls the async result endpoint.

Quick Start

Step 1: Create Supporting Resources

Create a synonym set in your Organization:

Create a search configuration referencing the synonym set:

Step 2: Create a Search Index Entity

SearchIndex is a Synapse Entity, not a standalone /search/index resource. Creation goes through the standard entity controller. Use the SearchIndex concrete type and provide a parentId (a Project or Folder):

Sample Response (201 Created):

Note: Index state (CREATING, ACTIVE, FAILED, DELETING) is stored in the indexing DB's SEARCH_INDEX_STATUS table and is not a property of the SearchIndex entity itself.

The index build is handled asynchronously by the SearchIndexLifecycleWorker. Builds are triggered on both create and update of the SearchIndex entity.

Step 3: Submit a Search Query

Search operations remain under the /repo/v1/search/* namespace.

Response (201 Created):

Step 4: Poll for Results

Poll until the job completes. If the index is still building (CREATING), the worker automatically retries — the client only polls this endpoint.

Response (200 OK when ready, 202 Accepted while processing):

Endpoint Summary

All URLs are prefixed with /repo/v1.

Configuration Resources

Note: SearchIndex CRUD (create, get, update, delete, trash/restore) is handled by the standard Synapse Entity API under /repo/v1/entity/* and is not enumerated above. SearchIndex behaves like other entity types (e.g., Table, View) with additional search-specific fields.

Search Operations

Security & Authorization

Organization-Scoped ACL for Configuration Resources

Configuration resources (SynonymSet, ColumnAnalyzerOverride, SearchConfiguration) belong to an Organization (via organizationId). Authorization reuses the existing Organization ACL model (same as JSON Schemas):

• ACL scope: Per-Organization (not per-resource).

• Public read: All configuration resources are publicly readable (no auth for GET/list).

• Mutating operations: Require appropriate ACCESS_TYPE on the Organization ACL.

• Admin bypass: Admins skip ACL checks (UserInfo.isAdmin()).

• Default ACL: When an Organization is created, the creator gets {READ, CREATE, CHANGE_PERMISSIONS, UPDATE, DELETE}.

TextAnalyzer endpoints are currently read-only (GET and LIST only) and publicly accessible. System analyzers are managed by the bootstrapper on startup; user-defined analyzer CRUD is not yet exposed via REST.

Data Plane: Search & Autocomplete

Actual behavior (mirrors MaterializedView authorization):

• Search queries and autocomplete requests are not public.

• To execute a search or autocomplete request, the caller must have:

  • READ on the SearchIndex entity and

  • Sufficient permissions to read from the source table referenced by definingSQL.

• The implementation loads data as the anonymous user when building the OpenSearch index:

  • The SearchIndexLifecycleWorker uses TableQueryManager.runQueryAsStream() with the anonymous user.

  • Only publicly accessible rows are indexed. Even if a caller has elevated permissions on the table, the underlying index contains only public rows; search results cannot leak non-public data.

Data Model

This section defines all JSON schema types used across the API. Configuration resources are regular REST objects stored in dedicated tables. SearchIndex is implemented as a Synapse Entity backed by NODE/NODE_REVISION, with a separate indexing DB holding status.

SynonymSet

SynonymRule

ColumnAnalyzerOverride

ColumnAnalyzerOverrideEntry

TextAnalyzer

TextAnalyzerSettings

SearchConfiguration

SearchIndex

The SearchIndex schema has only two explicit properties (everything else is inherited from Entity):

Note: Index state (CREATING, ACTIVE, FAILED, DELETING) is stored in the indexing DB's SEARCH_INDEX_STATUS table and is not a property of the SearchIndex entity itself.

As a Synapse Entity, SearchIndex also includes the standard entity fields inherited from Entity, such as:

• id

• concreteType (must be "org.sagebionetworks.repo.model.table.search.SearchIndex")

• parentId (Project or Folder)

• name

• etag

• createdOn, createdBy

• modifiedOn, modifiedBy

• versionNumber

• etc.

SearchIndexState

Index state is stored in the indexing DB, not on the entity itself.

SearchQuery

SearchResults

SearchHit