Migrating from API v1

API v2 Preview

API v2 is coming in an upcoming release. This guide previews the changes to help you prepare for migration. The current release uses API v1.

Novelty API v2 will introduce improvements to response formats, error handling, endpoint organization, and role-based access control. This guide previews the key changes to help you prepare for migration.

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
• Better error handling — Structured error responses with typed errors and actionable messages
• Safer responses — Response envelopes that include warnings without breaking existing integrations
• Fine-grained access control — Role-based permissions that map cleanly to organizational responsibilities

API Version Overview

Version	Status	Base Path	Notes
v1	Current	/api/v1/	Current API for all installations
v2	Preview	/api/v2/	Coming in an upcoming release

When v2 releases, both API versions will be available. Plan to migrate to v2 for new development.

Design Principles

V2 follows REST conventions more strictly than v1:

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.

Consistent path structure — Related operations are grouped under the same path prefix (/contexts/{context}/observations groups all observation operations under the context).

Endpoint Path Changes

The tables below show the mapping from v1 to v2 endpoints. Most changes follow the design principles above.

Admin Endpoints

Admin endpoints manage system configuration, monitoring, and cluster operations. Most admin endpoints remain unchanged since they already followed consistent patterns. The main changes involve clearer naming (build-info → system-info, meta-data → metadata) and restructuring node-specific operations under a /nodes/ path prefix.

v1 Endpoint	v2 Endpoint	Notes
GET /admin/build-info	GET /admin/system-info	Renamed
GET /admin/config	GET /admin/config	Unchanged
GET /admin/graph-hash-code	GET /admin/graph-hash-code	Unchanged
GET /admin/liveness	GET /admin/liveness	Unchanged
GET /admin/meta-data	GET /admin/metadata	Renamed (hyphen removed)
GET /admin/metrics	GET /admin/metrics	Unchanged
GET /admin/readiness	GET /admin/readiness	Unchanged
POST /admin/request-node-sleep/{id}	POST /admin/nodes/{nodeIdSegment}/request-sleep	Restructured path
POST /admin/shard-sizes	GET /admin/shards/size-limits	Split into separate read endpoint
POST /admin/shard-sizes	POST /admin/shards/size-limits	Split into separate write endpoint
POST /admin/shutdown	POST /admin/shutdown	Unchanged

Ingest Endpoints

Ingest endpoints manage data streaming into Novelty. The key changes apply the plural naming convention (/ingest → /ingests) and move the stream name from the URL path into the request body when creating new streams.

v1 Endpoint	v2 Endpoint	Notes
GET /ingest	GET /ingests	Pluralized
POST /ingest/{name}	POST /ingests	Name moved to request body
GET /ingest/{name}	GET /ingests/{name}	Pluralized
DELETE /ingest/{name}	DELETE /ingests/{name}	Pluralized

Cypher Query Endpoints

Cypher query endpoints execute ad-hoc queries against the graph. V2 moves these from /query/cypher to /cypher-queries and uses more descriptive operation names (query-graph, query-nodes, query-edges) that clarify what each endpoint returns. Note that Novelty restricts Cypher to read-only operations.

v1 Endpoint	v2 Endpoint	Notes
POST /query/cypher	POST /cypher-queries/query-graph	Restructured path
POST /query/cypher/nodes	POST /cypher-queries/query-nodes	Restructured path
POST /query/cypher/edges	POST /cypher-queries/query-edges	Restructured path
POST /query/cypher/user-defined	POST /cypher-queries/user-defined	Restructured path

Context Endpoints

Contexts are isolated environments for storing and querying observations. These endpoints are new in v2 and provide the primary interface for managing observation data in Novelty.

v1 Endpoint	v2 Endpoint	Notes
—	GET /contexts/{context}	New
—	POST /contexts/{context}/observations	New
—	POST /contexts/{context}/observations/bulk	New
—	DELETE /contexts/{context}/observations	New
—	DELETE /contexts/{context}	New

Transformation Endpoints

Transformations define how raw observations are processed before scoring. These endpoints are new in v2 and allow you to create, test, and manage transformation pipelines.

v1 Endpoint	v2 Endpoint	Notes
—	POST /transformations	New
—	POST /transformations/test	New
—	GET /transformations	New
—	GET /transformations/{transformation}	New
—	PUT /transformations/{transformation}	New
—	DELETE /transformations/{transformation}	New

Gremlin Endpoints

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

• POST /query/gremlin (deprecated)
• POST /query/gremlin/nodes (deprecated)
• POST /query/gremlin/edges (deprecated)

Use Cypher query endpoints instead.

Query UI Endpoints

Query UI endpoints configure the Exploration UI with sample queries, quick queries, and node appearance customizations. These endpoints remain unchanged in v2 since they already followed consistent patterns.

v1 Endpoint	v2 Endpoint	Notes
GET /query-ui/sample-queries	GET /query-ui/sample-queries	Unchanged
PUT /query-ui/sample-queries	PUT /query-ui/sample-queries	Unchanged
GET /query-ui/quick-queries	GET /query-ui/quick-queries	Unchanged
PUT /query-ui/quick-queries	PUT /query-ui/quick-queries	Unchanged
GET /query-ui/node-appearances	GET /query-ui/node-appearances	Unchanged
PUT /query-ui/node-appearances	PUT /query-ui/node-appearances	Unchanged

Key Changes

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

Response Format

v1 returned raw data directly at the top level of the response body. v2 wraps all responses in structured envelopes with content, message, and warnings fields. Update your response parsing to extract the content field:

# v1
ingest_config = response.json()

# v2
ingest_config = response.json()["content"]

See Response Format for the complete envelope specification.

Error Responses

v1 used varied error formats depending on the error type. v2 returns errors as an array of typed error objects with consistent structure, making error handling more predictable:

{
  "errors": [
    {
      "type": "ApiError",
      "message": "Ingest stream 'my-ingest' does not exist"
    }
  ]
}

Each error object includes a type field (ApiError, DecodeError, CypherError) that indicates how to interpret the remaining fields. This allows clients to handle different error categories appropriately.

See Error Responses for the complete error format specification.

Query Parameters

v2 standardizes common query parameters (namespace, at-time, timeout) that work consistently across all endpoints that support them. See Query Parameters for usage details.

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 Context 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:

v1:

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

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

v2:

POST /api/v2/ingests
Content-Type: application/json

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

This applies to ingests.

Migration Checklist

1. Update endpoint paths - Use the mapping tables above
2. Update HTTP methods - Some endpoints changed from PUT to POST
3. Move resource names to body - For create operations (ingests)
4. Update response parsing - Extract data from content field
5. Handle warnings - Check the warnings array in responses
6. Update error handling - Parse the new structured error format
7. Configure authentication - Ensure proper role assignments for RBAC

Questions

Contact support@thatdot.com if you have questions about migration or need assistance.

Related Documentation

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