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.

Quine API v2 introduces improvements to response formats, error handling, and endpoint organization. This guide explains the key changes and how to migrate your integrations from v1 to v2.

Why V2?¶

The v1 API evolved organically as Quine 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
Graph-scoped operations — Ingest, query, and standing query endpoints are scoped under a named graph (graph/quine), making multi-graph 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

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; will be removed in a future release

Both API versions are currently available. 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:

Graph-scoped resources — Operations on ingests, standing queries, Cypher, and algorithms are scoped under /graph/quine/ in the URL path. Quine uses a single graph named quine.

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 — Actions like :pause/:resume use POST because they trigger state changes. 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/graph-hash-code`	`GET /graph/quine/hashCode`	Graph-scoped, camelCase
`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/`
`POST /admin/request-node-sleep/{id}`	—	Removed
`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 endpoints manage data streaming into Quine. In v2, ingest operations are scoped under a named graph (/graph/quine/ingests). The stream name moved from the URL path to the request body when creating streams, and pause/resume operations use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`GET /ingest`	`GET /graph/quine/ingests`	Graph-scoped, pluralized
`POST /ingest/{name}`	`POST /graph/quine/ingests`	Name moved to request body
`GET /ingest/{name}`	`GET /graph/quine/ingests/{ingestName}`	Graph-scoped, param renamed
`DELETE /ingest/{name}`	`DELETE /graph/quine/ingests/{ingestName}`	Graph-scoped, param renamed
`PUT /ingest/{name}/pause`	`POST /graph/quine/ingests/{ingestName}:pause`	RPC-style verb, POST
`PUT /ingest/{name}/start`	`POST /graph/quine/ingests/{ingestName}:resume`	Renamed to `:resume`, POST

For ingest stream configuration and usage, see Ingest Streams.

Standing Query Endpoints¶

Standing queries are continuously-running pattern matchers that execute actions when patterns are detected in the graph. In v2, standing query operations are scoped under a named graph. Path segments use camelCase, and output management moves the output name into the request body.

v1 Endpoint	v2 Endpoint	Notes
`GET /query/standing`	`GET /graph/quine/standingQueries`	Graph-scoped, camelCase
`POST /query/standing/{name}`	`POST /graph/quine/standingQueries`	Name moved to request body
`GET /query/standing/{name}`	`GET /graph/quine/standingQueries/{standingQueryName}`	Graph-scoped, camelCase
`DELETE /query/standing/{name}`	`DELETE /graph/quine/standingQueries/{standingQueryName}`	Graph-scoped, camelCase
`POST /query/standing/{name}/output/{output}`	`POST /graph/quine/standingQueries/{standingQueryName}/outputs`	Output name in body
`DELETE /query/standing/{name}/output/{output}`	`DELETE /graph/quine/standingQueries/{standingQueryName}/outputs/{standingQueryOutputName}`	Graph-scoped, camelCase
`POST /query/standing/control/propagate`	`POST /graph/quine/standingQueries:propagate`	RPC-style verb

For standing query configuration and output destinations, see Standing Queries.

Cypher Query Endpoints¶

Cypher query endpoints execute ad-hoc queries against the graph. In v2, these are scoped under a named graph and use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`POST /query/cypher`	`POST /graph/quine/cypher:query`	Graph-scoped, RPC verb
`POST /query/cypher/nodes`	`POST /graph/quine/cypher:queryNodes`	Graph-scoped, RPC verb
`POST /query/cypher/edges`	`POST /graph/quine/cypher:queryEdges`	Graph-scoped, RPC verb

Algorithm Endpoints¶

Algorithm endpoints perform graph traversal operations like random walks. In v2, these are scoped under a named graph and use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`GET /algorithm/walk/{id}`	`POST /graph/quine/algorithms/randomWalk/nodes/{nodeId}:generateRandomWalk`	Graph-scoped, RPC verb, param renamed
`PUT /algorithm/walk`	`POST /graph/quine/algorithms/randomWalk:saveWalks`	Graph-scoped, RPC verb

Query UI Endpoints¶

Query UI endpoints configure the Exploration UI with sample queries, quick queries, and node appearance customizations. These have moved to camelCase path segments.

v1 Endpoint	v2 Endpoint	Notes
`GET /query-ui/sample-queries`	`GET /queryUi/sampleQueries`	camelCase
`PUT /query-ui/sample-queries`	`PUT /queryUi/sampleQueries`	camelCase
`GET /query-ui/quick-queries`	`GET /queryUi/quickQueries`	camelCase
`PUT /query-ui/quick-queries`	`PUT /queryUi/quickQueries`	camelCase
`GET /query-ui/node-appearances`	`GET /queryUi/nodeAppearances`	camelCase
`PUT /query-ui/node-appearances`	`PUT /queryUi/nodeAppearances`	camelCase

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.

Query Parameters¶

v2 standardizes common query parameters using camelCase names (atTime, timeout) that work consistently across all graph-scoped endpoints that support them. Timestamps use RFC 3339 format (e.g., 2026-04-27T15:30:00Z) instead of epoch milliseconds, and timeouts use duration strings (e.g., 20s) instead of millisecond integers. The namespace query parameter from previous versions is replaced by the graph name in the URL path (/graph/{graphName}/...). See Query Parameters for usage details.

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

v1:

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

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

v2:

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

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

This applies to ingests and standing queries.

Migration Checklist¶

Update base paths — /admin/ is now /system/; data operations are now under /graph/quine/
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, standing queries)
Update parameter names — name → ingestName, id → nodeId, standing-query-name → standingQueryName
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

REST API Reference - Interactive API documentation