Neo4j Query API

openapi: 3.1.0
info:
  title: Neo4j Aura Authentication Query API
  description: 'The Neo4j Aura API provides programmatic access to manage Neo4j AuraDB cloud database instances. It supports operations across three primary resources: instances, tenants, and snapshots. Developers authenticate using OAuth2 bearer tokens obtained through client credentials, and can automate the provisioning, configuration, and management of their cloud-hosted Neo4j graph databases. The API is accessible through the api.neo4j.io platform and is available to Aura Enterprise customers.'
  version: '1.0'
  contact:
    name: Neo4j Support
    url: https://support.neo4j.com
  termsOfService: https://neo4j.com/terms/
servers:
- url: https://api.neo4j.io/v1
  description: Neo4j Aura Production API
security:
- bearerAuth: []
tags:
- name: Query
  description: Execute Cypher queries using implicit transactions where the server manages transaction lifecycle automatically.
paths:
  /db/{databaseName}/query:
    post:
      operationId: executeQuery
      summary: Execute a Cypher query
      description: Executes a Cypher query against the specified database using an implicit transaction. The server wraps the submitted Cypher query in a transaction automatically so that if any part of the query fails the database is reverted to its state before the query was executed. Multiple statements can be sent in a single request and the server runs them in sequence.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/databaseName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: Invalid query or request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
        '404':
          description: Database not found
components:
  schemas:
    QueryStatistics:
      type: object
      description: Statistics about query execution.
      properties:
        contains_updates:
          type: boolean
          description: Whether the query modified the database
        nodes_created:
          type: integer
          description: Number of nodes created
        nodes_deleted:
          type: integer
          description: Number of nodes deleted
        properties_set:
          type: integer
          description: Number of properties set
        relationships_created:
          type: integer
          description: Number of relationships created
        relationships_deleted:
          type: integer
          description: Number of relationships deleted
        labels_added:
          type: integer
          description: Number of labels added to nodes
        labels_removed:
          type: integer
          description: Number of labels removed from nodes
        indexes_added:
          type: integer
          description: Number of indexes created
        indexes_removed:
          type: integer
          description: Number of indexes removed
        constraints_added:
          type: integer
          description: Number of constraints created
        constraints_removed:
          type: integer
          description: Number of constraints removed
    GraphRelationship:
      type: object
      description: A relationship returned in graph result format.
      properties:
        id:
          type: string
          description: The internal relationship ID
        type:
          type: string
          description: The relationship type
        startNode:
          type: string
          description: The ID of the start node
        endNode:
          type: string
          description: The ID of the end node
        properties:
          type: object
          description: Key-value properties of the relationship
          additionalProperties: true
    StatementResult:
      type: object
      description: Result of a single Cypher statement execution.
      properties:
        columns:
          type: array
          description: Column names in the result set
          items:
            type: string
        data:
          type: array
          description: Array of result rows
          items:
            type: object
            properties:
              row:
                type: array
                description: Row data values
                items: {}
              meta:
                type: array
                description: Metadata for each value in the row
                items: {}
              graph:
                type: object
                description: Graph representation of the result when requested
                properties:
                  nodes:
                    type: array
                    description: Graph nodes in the result
                    items:
                      $ref: '#/components/schemas/GraphNode'
                  relationships:
                    type: array
                    description: Graph relationships in the result
                    items:
                      $ref: '#/components/schemas/GraphRelationship'
        stats:
          $ref: '#/components/schemas/QueryStatistics'
    CypherStatement:
      type: object
      description: A single Cypher statement with optional parameters and result format.
      required:
      - statement
      properties:
        statement:
          type: string
          description: The Cypher query string to execute
          example: MATCH (n) RETURN n LIMIT 10
        parameters:
          type: object
          description: Named parameters for the Cypher query. Always use parameters instead of string concatenation to prevent Cypher injection.
          additionalProperties: true
          example:
            name: Alice
            age: 30
        resultDataContents:
          type: array
          description: Requested result formats. Possible values include row and graph.
          items:
            type: string
            enum:
            - row
            - graph
        includeStats:
          type: boolean
          description: Whether to include query execution statistics in the response
          default: false
    ErrorResponse:
      type: object
      description: Response containing one or more errors.
      properties:
        results:
          type: array
          description: Empty or partial results
          items: {}
        errors:
          type: array
          description: Array of errors that occurred
          items:
            $ref: '#/components/schemas/Neo4jError'
    QueryResponse:
      type: object
      description: Response containing query results from an implicit transaction.
      properties:
        results:
          type: array
          description: Array of result objects corresponding to each executed statement
          items:
            $ref: '#/components/schemas/StatementResult'
        errors:
          type: array
          description: Array of errors that occurred during execution
          items:
            $ref: '#/components/schemas/Neo4jError'
    QueryRequest:
      type: object
      description: Request body for executing one or more Cypher statements using an implicit transaction.
      required:
      - statements
      properties:
        statements:
          type: array
          description: Array of Cypher statements to execute
          items:
            $ref: '#/components/schemas/CypherStatement'
    Neo4jError:
      type: object
      description: An error returned by the Neo4j server.
      properties:
        code:
          type: string
          description: Neo4j error code in the format Neo.ErrorClassification.Category.Title
          example: Neo.ClientError.Statement.SyntaxError
        message:
          type: string
          description: Human-readable error message
          example: Invalid input 'X'
    GraphNode:
      type: object
      description: A node returned in graph result format.
      properties:
        id:
          type: string
          description: The internal node ID
        labels:
          type: array
          description: Labels assigned to the node
          items:
            type: string
        properties:
          type: object
          description: Key-value properties of the node
          additionalProperties: true
  parameters:
    databaseName:
      name: databaseName
      in: path
      required: true
      description: The name of the database to execute queries against. Use neo4j for the default database.
      schema:
        type: string
        example: neo4j
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token obtained from the /oauth/token endpoint using client credentials. Tokens expire after one hour.
externalDocs:
  description: Neo4j Aura API Specification
  url: https://neo4j.com/docs/aura/platform/api/specification/