REST API¶

Novelty exposes a JSON REST API under the path prefix /api/v2/. This page describes the conventions every endpoint shares — URL shape, request and response format, error envelope, and common query parameters. For the per-endpoint reference, see the interactive REST API Reference.

Quick start¶

A simple first request is /system/systemInfo, which returns version and build information about the running server:

curl http://localhost:8080/api/v2/system/systemInfo

If RBAC is configured (see Authentication below), every request needs a bearer token in the Authorization header:

curl http://localhost:8080/api/v2/system/systemInfo \
  -H "Authorization: Bearer <access_token>"

The example assumes the default localhost:8080 bind address — substitute your own host and port if you've configured the Novelty webserver differently. The response is JSON with the resource at the top level of the body. The sections below describe list and error responses, the URL conventions every endpoint follows, and the common query parameters available to most endpoints.

Authentication¶

Novelty supports OpenID Connect (OIDC) for authentication with role-based access control (RBAC). When RBAC is configured, every request requires a bearer token in the Authorization header.

For complete setup instructions including identity provider configuration, obtaining tokens, and role permissions, see OIDC Authentication Setup.

Interactive docs¶

The Novelty web server hosts interactive API docs at /docs. The UI lists every endpoint, shows full request and response schemas (including the deeply-nested options on Standing Queries and Ingest Streams), and lets you fill in parameters and run requests directly from the page.

The interactive view is powered by Stoplight Elements, which renders the OpenAPI specification served at /docs/openapi.json. The same spec can be fed to OpenAPI Generator to produce client libraries in your language of choice.

URL conventions¶

Every v2 endpoint shares the same shape. Decoding a URL like POST /api/v2/model/{modelName}/ingests/{ingestName}:pause takes only a few rules:

Base path — all v2 endpoints live under /api/v2/.
Model-scoped resources — operations on ingests, scoring, and transformations are nested under /model/{modelName}/.
System endpoints — administrative endpoints (config, metrics, liveness, …) live under /system/.
RPC-style actions — actions on a resource use a colon-separated verb (/ingests/{ingestName}:pause, /system:shutdown). Plain GET/POST/PUT/DELETE cover CRUD.
camelCase — path segments are camelCase (standingQueries, systemInfo), matching JSON field names.
Plural collections — collection paths are plural (/ingests); individual resources are singular (/ingests/{ingestName}).

These rules come from Google's API Improvement Proposals; see Design Principles for the AIP citation behind each rule.

Response format¶

Requests and responses are JSON. Endpoints that create or update a resource also accept YAML when the request Content-Type is application/yaml. Where a request body field is a tagged union (e.g., an ingest's format, an output destination's type), the "type": "<Kind>" discriminator uses bare PascalCase names like "Kinesis" or "S3Bucket", not SCREAMING_SNAKE_CASE. AIP-126's convention applies to enum values; a type discriminator identifies a schema variant, and the value matches the corresponding OpenAPI component name shown in the interactive docs.

Successful responses return the resource (or collection) directly at the top level of the body:

{
  "name": "my-ingest",
  "status": "RUNNING",
  "settings": { ... }
}

List endpoints wrap their results in an items envelope (per AIP-158):

{
  "items": [ ... ]
}

Every list response currently fits in a single page.

HTTP Status	Response Body
200 OK	Resource or collection
201 Created	Created resource (may include `Warning` header)
202 Accepted	Empty body
204 No Content	Empty body

Error responses¶

Errors are returned as a structured ApiError envelope shaped after AIP-193 / google.rpc.Status:

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

The error object contains:

Field	Description
`code`	HTTP status code (e.g., `400`, `404`, `500`)
`status`	Canonical AIP-193 status string (e.g., `NOT_FOUND`, `INVALID_ARGUMENT`, `INTERNAL`)
`message`	Human-readable error description
`details`	Array of additional error details (`ErrorInfo`, `Help`, or `RequestInfo`)

Switch on status rather than parse message. details[] is a closed union of ErrorInfo (machine-readable classification with a stable reason code like CYPHER_ERROR), Help (free-form hints), and RequestInfo — RequestInfo.requestId lets you locate the matching server-side log entry for a 500 response.

Query parameters¶

Common query parameters available across endpoints. Timestamps and durations follow AIP-142: RFC 3339 timestamps and Go-style duration strings.

Parameter	Description	Example
`atTime`	Historical query at a specific time (RFC 3339 timestamp)	`?atTime=2026-04-27T15:30:00Z`
`timeout`	Operation timeout as a duration string	`?timeout=20s`

Versioning¶

/api/v2/ is the current API and is what this page describes. /api/v1/ remains mounted by default unless RBAC is configured for backwards compatibility, but API v1 is planned for deprecation and will be removed in a future release. See Migrating from API v1 for the migration guide.