openapi: 3.1.0
info:
  title: Neo4j HTTP API
  description: >-
    The Neo4j HTTP API allows developers to execute Cypher queries against a
    Neo4j database through HTTP requests. It supports both implicit
    transactions, where the API handles transaction management automatically,
    and explicit transactions, where developers control the full transaction
    lifecycle including open, commit, and rollback operations. By default the
    API uses port 7474 for HTTP and port 7473 for HTTPS on self-managed
    instances.
  version: '5.0'
  contact:
    name: Neo4j Support
    url: https://support.neo4j.com
  termsOfService: https://neo4j.com/terms/
externalDocs:
  description: Neo4j HTTP API Documentation
  url: https://neo4j.com/docs/http-api/current/
servers:
  - url: http://localhost:7474
    description: Self-managed HTTP server
  - url: https://localhost:7473
    description: Self-managed HTTPS server
tags:
  - name: Discovery
    description: >-
      Server discovery endpoint that returns available endpoints, server
      version, edition, and authentication configuration.
  - name: Query
    description: >-
      Execute Cypher queries using implicit transactions where the server
      manages transaction lifecycle automatically.
  - name: Transactions
    description: >-
      Manage explicit transactions with full control over the transaction
      lifecycle including open, run, commit, and rollback operations.
security:
  - basicAuth: []
paths:
  /:
    get:
      operationId: getDiscovery
      summary: Discovery endpoint
      description: >-
        Returns a list of available endpoints on the Neo4j installation,
        together with basic server information including the Neo4j version,
        edition, Bolt connection URIs, and authentication configuration. This
        endpoint does not require authentication.
      tags:
        - Discovery
      security: []
      responses:
        '200':
          description: Server discovery information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryResponse'
  /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
  /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:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using the Neo4j database username and
        password encoded as a base64 hash.
  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
  schemas:
    DiscoveryResponse:
      type: object
      description: >-
        Server discovery information including available endpoints, version,
        and connection details.
      properties:
        bolt_routing:
          type: string
          description: Neo4j Bolt routing connection URI for clustered deployments
          example: neo4j://localhost:7687
        bolt_direct:
          type: string
          description: Direct Bolt connection URI
          example: bolt://localhost:7687
        transaction:
          type: string
          description: URI pattern for the transaction endpoint
          example: /db/{databaseName}/tx
        neo4j_version:
          type: string
          description: The version of the Neo4j server
          example: '5.26.0'
        neo4j_edition:
          type: string
          description: The edition of the Neo4j server
          enum:
            - community
            - enterprise
          example: enterprise
    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'
    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'
    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
    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'
    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'
    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'
    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
    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
    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
    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'
    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'