Interactive API Docs¶

API v2 Coming Soon

API v2 introduces improved response formats, consistent error handling, and role-based access control. The current release uses API v1. See Migrating from API v1 for a preview of what's changing.

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/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¶

API responses are wrapped in structured envelopes that provide consistent access to response data, messages, and warnings.

{
  "content": {
    "name": "my-ingest",
    "status": "Running",
    "settings": { ... }
  },
  "message": "Ingest stream retrieved successfully",
  "warnings": []
}

HTTP Status	Envelope Type	Fields
200 OK	`Ok`	`content`, `message` (optional), `warnings`
201 Created	`Created`	`content`, `message` (optional), `warnings`
202 Accepted	`Accepted`	`message`, `monitorUrl` (optional)
204 No Content	`NoContent`	(empty body)

Extract the content field to access the response data:

response = requests.get(f"{base_url}/api/v2/ingests/{name}")
ingest_config = response.json()["content"]
warnings = response.json().get("warnings", [])

Error Responses¶

Errors are returned as an array of typed error objects:

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

Error object types include:

ApiError: General API errors with a message field
DecodeError: Request parsing errors with message and optional help fields
CypherError: Cypher query errors with a message field

HTTP status codes map to error response types: BadRequest (400), Unauthorized (401), NotFound (404), ServerError (500), ServiceUnavailable (503).

Query Parameters¶

Common query parameters available across endpoints:

Parameter	Description	Example
`at-time`	Historical query at specific time (milliseconds)	`?at-time=1704067200000`
`timeout`	Operation timeout in milliseconds	`?timeout=30000`