Skip to content

Interactive API Docs

API v2 is now the default

The v2 API is the default, with improved response formats, consistent error handling. API v1 remains available — and is still mounted by default — 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 Quine 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.

API Docs

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.

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