Interactive API Docs¶

API v2 is now the default

The v2 API is the default, with improved response formats, consistent error handling, and role-based access control. API v1 remains available — and is still mounted by default unless RBAC is configured — but API v1 is planned for deprecation and will be removed in a future release. See Migrating from API v1 for migration guidance.

The REST API documentation is served by the Novelty web server at /docs and lists out all of the endpoints, how to call them, and some inline descriptions of what they do. The UI even makes it possible to interactively try out endpoints by filling in text fields and clicking buttons.

The interactive documentation is powered by Stoplight Elements, which renders the OpenAPI specification of our API (accessible at /docs/openapi.json). This specification can also be used to generate client programs that call the API in the correct format. See OpenAPI Generator for more details.

This interactive documentation also includes a detailed specification of every API, describing all optional and required values, and showing what the possible options are. In some of the API endpoints (like Standing Queries or Ingest Streams) these options can be very complicated and detailed, with many options available. All available options are shown in this "Schema" section.

For the complete endpoint reference, see the REST API Reference.

Authentication¶

Novelty uses OpenID Connect (OIDC) for authentication with role-based access control (RBAC). API requests require a bearer token in the Authorization header:

curl -X GET http://localhost:8080/api/v2/graph/quine/ingests \
  -H "Authorization: Bearer <access_token>"

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

Response Format¶

Successful API responses return the resource or collection directly as the top-level JSON object or array:

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

List endpoints return paginated results:

{
  "items": [ ... ],
  "nextPageToken": "..."
}

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

response = requests.get(f"{base_url}/api/v2/graph/quine/ingests/{ingest_name}")
ingest_config = response.json()

Error Responses¶

Errors are returned as a structured ApiError object:

{
  "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`	Status string (e.g., `NOT_FOUND`, `INVALID_ARGUMENT`, `INTERNAL`)
`message`	Human-readable error description
`details`	Array of additional error details (`ErrorInfo`, `Help`, or `RequestInfo`)

Query Parameters¶

Common query parameters available across endpoints:

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`