Neo4j Transactions API

openapi: 3.1.0
info:
  title: Neo4j Aura Authentication Transactions 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: Transactions
  description: Manage explicit transactions with full control over the transaction lifecycle including open, run, commit, and rollback operations.
paths:
  /db/{databaseName}/tx:
    post:
      operationId: openTransaction
      summary: Open a new explicit transaction
      description: Opens a new explicit transaction on the specified database. The response includes the transaction location URI which contains the transaction ID needed for subsequent operations. Optionally, Cypher statements can be included in the request body to be executed as part of the transaction opening. Transactions expire automatically after a period of inactivity with a default timeout of 30 seconds, configurable via server.http.transaction_idle_timeout.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/databaseName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '201':
          description: Transaction opened successfully
          headers:
            Location:
              description: URI of the new transaction
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
        '404':
          description: Database not found
  /db/{databaseName}/tx/{transactionId}:
    post:
      operationId: executeInTransaction
      summary: Execute statements in an open transaction
      description: Submits one or more Cypher statements to be executed within an existing open transaction. The transaction remains open after execution and must be explicitly committed or rolled back. Each request resets the transaction idle timeout.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/transactionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '200':
          description: Statements executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
        '404':
          description: Transaction or database not found
    delete:
      operationId: rollbackTransaction
      summary: Rollback a transaction
      description: Rolls back an open transaction, restoring the database to the state it was in before the transaction was opened. All changes made within the transaction are discarded.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/transactionId'
      responses:
        '200':
          description: Transaction rolled back successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '401':
          description: Authentication required
        '404':
          description: Transaction or database not found
  /db/{databaseName}/tx/{transactionId}/commit:
    post:
      operationId: commitTransaction
      summary: Commit a transaction
      description: Commits an open transaction, making all changes permanent in the database. Optionally, final Cypher statements can be included in the request body to be executed before the transaction is committed.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/transactionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequest'
      responses:
        '200':
          description: Transaction committed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Invalid request or transaction error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
        '404':
          description: Transaction or 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'
    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'
    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'
    TransactionRequest:
      type: object
      description: Request body for executing Cypher statements within a transaction.
      properties:
        statements:
          type: array
          description: Array of Cypher statements to execute within the transaction
          items:
            $ref: '#/components/schemas/CypherStatement'
    TransactionResponse:
      type: object
      description: Response from a transaction operation.
      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'
        commit:
          type: string
          description: URI to commit the transaction
          example: http://localhost:7474/db/neo4j/tx/1/commit
        transaction:
          type: object
          description: Transaction metadata
          properties:
            expires:
              type: string
              description: Timestamp when the transaction will expire if idle
              example: Wed, 01 Jan 2025 12:00:30 +0000
    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
    transactionId:
      name: transactionId
      in: path
      required: true
      description: The unique identifier of an open transaction, returned in the Location header when a transaction is opened.
      schema:
        type: string
  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/