Migrating from API v1¶

API v1 deprecation

API v1 is planned for deprecation and will be removed in a future release. New integrations should use v2; existing v1 integrations should plan to migrate.

Novelty API v2 introduces improvements to response formats, error handling, endpoint organization, and role-based access control. This guide explains the key changes and how to migrate your integrations from v1 to v2.

Why V2?¶

The v1 API evolved organically as Novelty grew, resulting in inconsistencies that made the API harder to learn and use. V2 addresses these issues with a ground-up redesign focused on:

Predictable patterns — Consistent naming conventions and HTTP method usage across all endpoints
Model-scoped operations — Ingest, scoring, and transformation endpoints are scoped under a named model (model/{modelName}), making multi-model support explicit in the URL
RPC-style actions — Action endpoints use colon-separated verbs (:pause, :resume, :shutdown) to clearly distinguish actions from resource operations
Better error handling — Structured error responses with actionable messages
Fine-grained access control — Role-based permissions that map cleanly to organizational responsibilities

API Version Overview¶

Version	Status	Base Path	Notes
v2	Current (default)	`/api/v2/`	Default API for all installations
v1	Planned for deprecation	`/api/v1/`	Still mounted by default unless RBAC is configured; will be removed in a future release

Both API versions are currently available. When RBAC/authentication is configured, only v2 is mounted. Otherwise, v1 routes remain reachable for backwards compatibility. Migrate to v2 for all new development and plan migration of existing integrations.

Design Principles¶

V2 follows REST conventions more strictly than v1:

Model-scoped resources — Operations on ingests, scoring, and transformations are scoped under /model/{modelName}/ in the URL path. Novelty supports multiple named models. There is no default model — you must create one before recording observations.

RPC-style action verbs — Action endpoints use a colon-separated verb suffix (e.g., ingests/{ingestName}:pause, system:shutdown). This clearly distinguishes actions from CRUD operations on resources.

camelCase path segments — Path segments use camelCase (standingQueries, shardSizeLimits, systemInfo) instead of kebab-case (standing-queries, shard-sizes, system-info).

System endpoints at top level — Administrative endpoints are grouped under /system/ (renamed from /admin/).

Plural resource names — Collection endpoints use plural nouns (/ingests not /ingest) to distinguish collections from individual resources.

Resource names in request body — When creating resources, the name is part of the resource representation in the request body, not the URL. This allows the server to validate the complete resource definition before accepting it.

POST for actions, PUT for idempotent updates — PUT is reserved for idempotent operations where repeating the request produces the same result.

Endpoint Path Changes¶

The tables below show the mapping from v1 to v2 endpoints. All v2 paths are relative to /api/v2/.

System Endpoints¶

System endpoints (formerly "admin") manage system configuration, monitoring, and cluster operations. These have moved from /admin/ to /system/ and path segments now use camelCase.

v1 Endpoint	v2 Endpoint	Notes
`GET /admin/build-info`	`GET /system/systemInfo`	Renamed, moved to `/system/`
`GET /admin/config`	`GET /system/config`	Moved to `/system/`
`GET /admin/ingest-usage`	—	Removed (see `licenseUsage`)
—	`GET /system/licenseUsage`	New
`GET /admin/liveness`	`GET /system/liveness`	Moved to `/system/`
`GET /admin/metrics`	`GET /system/metrics`	Moved to `/system/`
`GET /admin/readiness`	`GET /system/readiness`	Moved to `/system/`
—	`GET /system/roles`	New
`POST /admin/shard-sizes`	`GET /system/shardSizeLimits`	Split into GET, moved, camelCase
`POST /admin/shard-sizes`	`PATCH /system/shardSizeLimits`	Split into PATCH, moved, camelCase
`POST /admin/shutdown`	`POST /system:shutdown`	RPC-style verb

Ingest Endpoints¶

Ingest (novelty stream) endpoints manage data streaming into Novelty. In v2, ingest operations are scoped under a named model (/model/{modelName}/ingests). The stream name moved from the URL path to the request body when creating streams.

v1 Endpoint	v2 Endpoint	Notes
`GET /novelty/stream`	`GET /model/{modelName}/ingests`	Model-scoped, restructured
`POST /novelty/stream`	`POST /model/{modelName}/ingests`	Model-scoped
`GET /novelty/stream/{name}`	`GET /model/{modelName}/ingests/{ingestName}`	Model-scoped, param renamed
`DELETE /novelty/stream/{name}`	`DELETE /model/{modelName}/ingests/{ingestName}`	Model-scoped, param renamed

Scoring Endpoints¶

Scoring endpoints record and query observations. In v2, these are scoped under a named model and use RPC-style verbs. There is no default model — you must create one before recording observations.

v1 Endpoint	v2 Endpoint	Notes
`POST /novelty/{namespace}/observe`	`POST /model/{modelName}:record`	Renamed, model-scoped
`POST /novelty/{namespace}/read`	`POST /model/{modelName}:read`	Model-scoped, RPC verb
`DELETE /novelty/{namespace}/remove`	`POST /model/{modelName}:remove`	Model-scoped, RPC verb
`POST /novelty/{namespace}/observe/bulk`	`POST /model/{modelName}:batchRecord`	Model-scoped, RPC verb
`POST /novelty/{namespace}/read/bulk`	`POST /model/{modelName}:batchRead`	Model-scoped, RPC verb
`DELETE /novelty/{namespace}/remove/bulk`	`POST /model/{modelName}:batchRemove`	Model-scoped, RPC verb

Sliding Window Endpoints¶

v1 Endpoint	v2 Endpoint	Notes
`GET /novelty/{namespace}/sliding-window/config`	`GET /model/{modelName}/slidingWindows`	Model-scoped, camelCase
`PUT /novelty/{namespace}/sliding-window/config`	`PUT /model/{modelName}/slidingWindows`	Model-scoped, camelCase
`DELETE /novelty/{namespace}/sliding-window/config`	`DELETE /model/{modelName}/slidingWindows`	Model-scoped, camelCase

Transformation Endpoints¶

Transformations define how raw observations are processed before scoring. In v2, transformations are scoped under a named model.

v1 Endpoint	v2 Endpoint	Notes
`GET /novelty/transforms`	`GET /model/{modelName}/transformations`	Model-scoped
`POST /novelty/transforms`	`POST /model/{modelName}/transformations`	Model-scoped
`GET /novelty/transforms/{transformation}`	`GET /model/{modelName}/transformations/{transformationName}`	Model-scoped, param renamed
`DELETE /novelty/transforms/{transformation}`	`DELETE /model/{modelName}/transformations/{transformationName}`	Model-scoped, param renamed
`POST /novelty/transforms/{transformation}/learn`	`POST /model/{modelName}/transformations:learn`	RPC verb, name in body
`POST /novelty/test-transform`	`POST /model/{modelName}/transformations/{transformationName}:evaluate`	Renamed, model-scoped

Model Namespace Endpoints¶

Models (formerly "contexts") are isolated environments for scoring observations. Model management endpoints have moved to /system/models. There is no default model — you must create one explicitly.

v1 Endpoint	v2 Endpoint	Notes
—	`GET /system/models`	New
—	`POST /system/models`	New
—	`DELETE /system/models/{modelName}`	New

Gremlin Endpoints¶

Gremlin was an alternative graph query language supported in v1. These endpoints are not available in v2. Cypher provides equivalent functionality with better performance and a more intuitive syntax:

POST /query/gremlin (v1 only)
POST /query/gremlin/nodes (v1 only)
POST /query/gremlin/edges (v1 only)

Use Cypher query endpoints instead.

Key Changes¶

This section describes behavioral changes that affect how you interact with the API, regardless of which endpoints you use.

Response Format¶

Both v1 and v2 return data directly at the top level of the response body. List endpoints in v2 return paginated results with items and nextPageToken fields. v2 201 responses may include a Warning header with advisory messages.

See Response Format for the complete response specification.

Error Responses¶

v1 used varied error formats depending on the error type. v2 returns a unified ApiError with structured details:

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "Ingest stream 'my-ingest' does not exist",
    "details": []
  }
}

The error object includes code, status, message, and details fields for consistent error handling across all endpoints.

See Error Responses for the complete error format specification.

Role-Based Access Control¶

v2 introduces role-based permissions. Each endpoint requires specific capabilities, and predefined roles (SuperAdmin, Administrator, Architect, DataEngineer, Analyst, Billing) grant sets of capabilities.

See OIDC/RBAC Setup for roles, capabilities, and configuration details.

Novelty Cypher Restrictions¶

In Novelty, Cypher query endpoints are read-only. Any query that attempts to modify the graph will return an error. Use the Model and Transformation APIs to manage data.

Resource Creation Pattern¶

API v2 uses a consistent pattern for creating resources where the resource name is in the request body rather than the URL path, and the resource is scoped to a model:

v1:

POST /api/v1/ingest/my-ingest-name
Content-Type: application/json

{ "type": "FileIngest", ... }

v2:

POST /api/v2/model/{modelName}/ingests
Content-Type: application/json

{ "name": "my-ingest-name", "type": "FileIngest", ... }

This applies to ingests and models.

Migration Checklist¶

Update base paths — /admin/ is now /system/; data operations are now under /model/{modelName}/
Update to camelCase — Path segments changed from kebab-case to camelCase (e.g., standing-queries → standingQueries)
Adopt RPC-style verbs — Action endpoints use colon verbs (e.g., /ingests/{name}/pause → /ingests/{ingestName}:pause)
Update HTTP methods — Some endpoints changed from PUT/GET to POST
Move resource names to body — For create operations (ingests, models)
Update parameter names — name → ingestName, id → nodeId, standing-query-name → standingQueryName, transformation → transformationName
Update query parameter formats — at-time → atTime (RFC 3339 timestamp), timeout → timeout (duration string like 20s)
Update error handling — Parse the new structured ApiError format with code, status, message, details
Configure authentication — Ensure proper role assignments for RBAC

REST API Reference - Interactive API documentation
OIDC/RBAC Setup - Authentication and authorization