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