Skip to content

REST API

Quine 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

The example assumes the default localhost:8080 bind address — substitute your own host and port if you've configured the Quine 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.

Interactive docs

The Quine 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.

API Docs

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/graph/quine/ingests/{ingestName}:pause takes only a few rules:

  • Base path — all v2 endpoints live under /api/v2/.

  • Graph-scoped resources — operations on ingests, standing queries, Cypher, and algorithms are nested under /graph/quine/. Quine uses a single graph named quine.

  • 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 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.