Neo4j REST API

The Neo4j REST API is designed with discoverability in mind, so that you can start with a GET / and from there discover URIs to do other stuff. Examples below uses URIs for examples; they are subject to change in the future, so for future-proofness discover URIs where possible, instead of relying on current layout. The default representation is json, both for responses and for data sent with POST/PUT requests.

Below follows a listing of ways to interact with the REST API. You can also see a (at runtime) generated description of the API be pointing your browser to the (exact URI may vary) http://localhost:7474/db/data/application.wadl

To interact with the JSON interface you must explicitly set request header Accept:application/json for those requests that responds with data. You should also set header Content-Type:application/json if your request sends data, for example when you're creating a relationship.

Ways to interact

Get root

GET /

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/

Response

200
{
  "node" : "http://localhost:7474/db/data/node",
  "node_index" : "http://localhost:7474/db/data/index/node",
  "relationship_index" : "http://localhost:7474/db/data/index/relationship",
  "reference_node" : "http://localhost:7474/db/data/node/0",
  "extensions_info" : "http://localhost:7474/db/data/ext",
  "extensions" : {
  }
}

Create empty node

POST /node

Example using curl

curl -H Accept:application/json -X POST http://localhost:7474/db/data/node

Response

201: OK, a node was created

Location: http://localhost:7474/db/data/node/123

Create node with properties

POST /node

{ "name": "Thomas Anderson",
  "profession": "Hacker"
}

Example using curl

curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"name": "Thomas Anderson", "profession": "Hacker"}' http://localhost:7474/db/data/node

Response

201: OK, a node was created

Location: http://localhost:7474/db/data/node/123

400: Invalid data sent

Get node

GET /node/123

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/node/123

Response

200: OK
{ "self": "http://localhost:7474/db/data/node/123",
  "data": { "name": "Thomas Anderson",
            "age": 29
  },
  "create_relationship": "http://localhost:7474/db/data/node/123/relationships",
  "all_relationships": "http://localhost:7474/db/data/node/123/relationships/all",
  "all_typed relationships": "http://localhost:7474/db/data/node/123/relationships/all/{-list|&|types}",
  "incoming_relationships": "http://localhost:7474/db/data/node/123/relationships/in",
  "incoming_typed relationships": "http://localhost:7474/db/data/node/123/relationships/in/{-list|&|types}",
  "outgoing_relationships": "http://localhost:7474/db/data/node/123/relationships/out",
  "outgoing_typed relationships": "http://localhost:7474/db/data/node/123/relationships/out/{-list|&|types}",
  "properties": "http://localhost:7474/db/data/node/123/properties",
  "property": "http://localhost:7474/db/data/node/123/property/{key}",
  "traverse": "http://localhost:7474/db/data/node/123/traverse/{returnType}"
}
404: Node not found

Set properties on node

Replaces all properties on a node with the supplied set of properties.

PUT /node/123/properties

{ "name": "Thomas Anderson",
  "profession": "Hacker"
}

Example using curl

curl -H Content-Type:application/json -X PUT -d '{"name": "Thomas Anderson", "profession": "Hacker"}' http://localhost:7474/db/data/node/123/properties

Response

204: OK, no content returned
400: Invalid data sent
404: Node node found

Get properties on node

GET /node/123/properties

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/node/123/properties

Response

200: OK
{ "name": "Thomas Anderson",
  "profession": "Hacker"
}
204: OK, no properties found
404: Node not found

Remove properties from node

Removes all properties from a node.

DELETE /node/123/properties

Example using curl

curl -X DELETE http://localhost:7474/db/data/node/123/properties

Response

204: OK, no content returned
404: Node not found

Set property on node

PUT /node/123/properties/foo

"the_value"

Example using curl

curl -H Content-Type:application/json -X PUT -d '"the_value"' http://localhost:7474/db/data/node/123/properties/foo

Response

204: OK, no content returned
400: Invalid data sent

Get property on node

GET /node/123/properties/foo

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/node/123/properties/foo

Response

200: OK
"the_value"
404: Node or property not found

Remove property from node

DELETE /node/123/properties/foo

Example using curl

curl -X DELETE http://localhost:7474/db/data/node/123/properties/foo

Response

204: OK, no content returned
404: Node or property not found

Delete node

DELETE /node/123

Example using curl

curl -X DELETE http://localhost:7474/db/data/node/123

Response

204: OK, no content returned
404: Node not found
409: Node could not be deleted (still has relationships?)

Create relationship

POST /node/123/relationships

{ "to": "http://localhost:7474/db/data/node/152",
  "data": { "date", 1270559208258 },
  "type": "KNOWS"
}

Example using curl

curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"to": "http://localhost:7474/db/data/node/152", "data": {"date": 1270559208258}, "type": "KNOWS"}' http://localhost:7474/db/data/node/123/relationships

Response

201: OK, a relationship was created

Location: http://localhost:7474/db/data/relationship/456

400: Invalid data sent
404: "to" node, or the node specified by the URI not found

Set properties on relationship

Replaces all properties on a relationship with the supplied set of properties.

PUT /relationship/456/properties

{ "date": 1270559208258 }

Example using curl

curl -H Content-Type:application/json -X PUT -d '{"date": 1270559208258}' http://localhost:7474/db/data/relationship/456/properties

Response

204: OK, no content returned
400: Invalid data sent
404: Relationship node found

Get properties on relationship

GET /relationship/456/properties

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/relationship/456/properties

Response

200: OK
{ "date": 1270559208258 }
204: OK, no properties found
404: Relationship not found

Remove properties from relationship

Removes all properties from a relationship.

DELETE /relationship/456/properties

Example using curl

curl -X DELETE http://localhost:7474/db/data/relationship/456/properties

Response

204: OK, no content returned
404: Relationship not found

Set property on relationship

PUT /relationship/456/properties/foo

"the_value"

Example using curl

curl -H Content-Type:application/json -X PUT -d '"the_value"' http://localhost:7474/db/data/relationship/456/properties/foo

Response

204: OK, no content returned
400: Invalid data sent
404: Relationship not found

Get property on relationship

GET /relationship/456/properties/foo

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/relationship/456/properties/foo

Response

200: OK
"the_value"
404: Relationship or property not found

Remove property from relationship

DELETE /relationship/456/properties/foo

Example using curl

curl -X DELETE http://localhost:7474/db/data/relationship/456/properties/foo

Response

204: OK, no content returned
404: Relationship or property not found

Delete relationship

DELETE /relationship/456

Example using curl

curl -X DELETE http://localhost:7474/db/data/relationship/456

Response

204: OK, no content returned
404: Relationship not found

Get relationships on node

GET /node/123/relationships/{dir}/{-list|&|types}

Where dir is one of all,in,out and types is an ampersand-separated list of types. Some examples:

  • GET /node/123/relationships/out/KNOWS&LOVES -- outgoing relationships of types KNOWS and LOVES
  • GET /node/123/relationships/all/KNOWS -- relationships (both outgoing and incoming) of type LOVES
  • GET /node/123/relationships/in -- incoming relationships

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/node/123/relationships/out/KNOWS\&LOVES

Note: The ''&'' must be esaped in bash-like terminals (as included in the example, ''\'')

Response

200: OK
[
  { "self": "http://localhost:7474/db/data/relationship/56",
    "start": "http://localhost:7474/db/data/node/123",
    "end": "http://localhost:7474/db/data/node/93",
    "type": "KNOWS",
    "properties": "http://localhost:7474/db/data/relationship/56/properties",
    "property": "http://localhost:7474/db/data/relationship/56/properties/{key}",
    "data": { "date", 1270559208258 }
  },
  { "self": "http://localhost:7474/db/data/relationship/834",
    "start": "http://localhost:7474/db/data/node/32",
    "end": "http://localhost:7474/db/data/node/123",
    "type": "LOVES",
    "properties": "http://localhost:7474/db/data/relationship/834/properties",
    "property": "http://localhost:7474/db/data/relationship/834/properties/{key}",
    "data": { "date", 1270559203821 }
  }
]
404: Node not found

Listing node indexes

GET /index/node

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/index/node

Response

200: OK
{
  "my_nodes" : {
    "template" : "http://localhost:7474/db/data/index/node/my_nodes/{key}/{value}",
    "provider" : "lucene",
    "type" : "exact"
  }
}

Add indices with provided configuration parameters

POST /index/node

Example using curl

curl-X POST -H Accept:application/json -HContent-Type:application/json -d '{"name":"fulltext", "config":{"type":"fulltext","provider":"lucene"}}' http://localhost:7474/db/data/index/node

Response

200: OK
{
  "template" : "http://localhost:7474/db/data/index/node/testing-fulltext/{key}/{value}",
  "provider" : "lucene",
  "type" : "fulltext"
}

Listing relationship indexes

GET /index/relationship

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/index/relationship

Response

200: OK
{
  "my_relationships" : {
    "template" : "http://localhost:7474/db/data/index/relationship/my_relationships/{key}/{value}",
    "provider" : "lucene",
    "type" : "exact"
  }
}

Add to index

POST /index/node/my_nodes/the_key/the_value

"http://localhost:7474/db/data/node/123"

Example using curl

curl -HContent-Type:application/json -X POST -d '"http://localhost:7474/db/data/node/123"' http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space

Response

201: OK, indexed the node with key/value

Location: http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space/123

POST /index/relationship/my_relationships/the_key/the_value

"http://localhost:7474/db/data/relationship/456"

Example using curl

curl -HContent-Type:application/json -X POST -d '"http://localhost:7474/db/data/relationship/123"' http://localhost:7474/db/data/index/relationship/my_relationships/the_key/the_value

Response

201: OK, indexed the node with key/value

Location: http://localhost:7474/db/data/index/relationships/my_relationships/the_key/the_value/456

Remove from index

DELETE /index/node/my_nodes/the_key/the_value/123

Such a URI is gotten from either a query to an index, where they will be included in the node/relationship returned representation. They are also returned (as Location in response header) when adding to an index.

Similarly for relationship indexes.

Example using curl

curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value/123

Response

204: OK, no content returned
404: Index entry not found

Remove from index without supplying value

DELETE /index/node/my_nodes/the_key/123

Will remove all indexing for node 123 and the specified key irregardless of value. Similarly for relationship indexes.

Example using curl

curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/the_key/123

Response

204: OK, no content returned

Remove from index with supplying neither key nor value

DELETE /index/node/my_nodes/123

Will remove all indexing for node 123 irregardless of key and value. Similarly for relationship indexes.

Example using curl

curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/123

Response

204: OK, no content returned

Query index -- Exact

There are two ways to query an index - using the get method, or the more advanced query method. Use the first for exact matches, and the second for advanced index querying.

This is the simple, exact matching get operation.

GET /index/node/my_nodes/the_key/the_value

GET /index/relationship/my_rels/the_key/the_value

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space
curl -H Accept:application/json http://localhost:7474/db/data/index/relationship/my_rels/the_key/the_value%20with%20space

Response

200: OK
[
  { "self": "http://localhost:7474/db/data/node/5",
    "data": { "name": "Thomas Anderson" },
    ...
    "indexed": "http://localhost:7474/db/data/index/node/the_key/the_value/5"
  },
  { "self": "http://localhost:7474/db/data/node/325",
    "data": { "name": "Agent Smith" },
    ...
    "indexed": "http://localhost:7474/db/data/index/node/the_key/the_value%20with%20space/325"
  }
]

The response is an ordered list of node or relationship representations, with one new property added: indexed. This property can be used to remove the indexed entity at a later point.

Query index -- Advanced

This is the advanced query operation for an index.

GET /index/node/my_nodes/the_key?query=the_value

GET /index/relationship/my_rels/the_key?query=the_value

Example using curl

curl -H Accept:application/json http://localhost:7474/db/data/index/node/my_nodes/the_key?query=the_value%20with%20space
curl -H Accept:application/json http://localhost:7474/db/data/index/relationship/my_rels/the_key?query=the_value%20with%20space

The response is an ordered list of node/relationship representations.

Traverse

POST /node/123/traverse/{returnType}

Where returnType is one if node, relationship, path and specifies which kind of objects to return in the response.

The position object in the body of the prune evaluator is a org.neo4j.graphdb.Path object representing the path from the start node to the current traversal position.

{
  "order": "depth first",
  "uniqueness": "node path",
  "relationships": [
    { "type": "KNOWS", "direction": "out" },
    { "type": "LOVES" }
  ],
  "prune evaluator": {
    "language": "javascript",
    "body": "position.endNode().getProperty('date')>1234567;"
  },
  "return filter": {
    "language": "builtin",
    "name": "all"
  },
  "max depth": 2
}

"max depth" is a short-hand way of specifying a prune evaluator which prunes after a certain depth. If not specified a max depth of 1 is used and if a "prune evaluator" is specified instead of a max depth, no max depth limit is set.

Builtin prune evaluators: none

Builtin return filters: all, all but start node

Example using curl

curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"order":"depth first"}' http://localhost:7474/db/data/node/123/traverse/node

Response

200: OK

If returnType=node:

[
  { "self": "http://localhost:7474/db/data/node/64",
    "data": { "name": "Thomas Anderson" },
    ...
  },
  { "self": "http://localhost:7474/db/data/node/635",
    "data": { "name": "Agent Smith" },
    ...
  }
]

If returnType=relationship:

[
  { "self": "http://localhost:7474/db/data/relationship/48",
    "data": { "date", 1270559208258 },
    ...
  },
  { "self": "http://localhost:7474/db/data/relationship/75",
    "data": { "date", 1270559209483 },
    ...
  }
]

If returnType=path:

[
  { "nodes": [
      "http://localhost:7474/db/data/node/2",
      "http://localhost:7474/db/data/node/351",
      "http://localhost:7474/db/data/node/64"
    ],
    "relationships": [
      "http://localhost:7474/db/data/relationship/5",
      "http://localhost:7474/db/data/relationship/48"
    ],
    "start": "http://localhost:7474/db/data/node/2",
    "end": "http://localhost:7474/db/data/node/64",
    "length": 3
  },
  { "nodes": [
      "http://localhost:7474/db/data/node/2",
      "http://localhost:7474/db/data/node/351",
      "http://localhost:7474/db/data/node/635"
    ],
    "relationships": [
      "http://localhost:7474/db/data/relationship/5",
      "http://localhost:7474/db/data/relationship/75"
    ],
    "start": "http://localhost:7474/db/data/node/2",
    "end": "http://localhost:7474/db/data/node/635",
    "length": 3
  },
]
404: Node not found

Finding a path between two nodes

POST /node/123/path

{ "to": "http://localhost:7474/db/data/node/456",
  "relationships": {"type": "KNOWS", "direction": "out"},
  "max depth": 3,
  "algorithm", "shortestPath"
}

The "algorithm" parameter should match the name of the corresponding method in GraphAlgoFactory. Currently supported algos are: shortestPath, allPaths, allSimplePaths and dijkstra.

Example using curl

curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/path -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"shortestPath"}'
curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/path -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"dijkstra","cost property":"cost","default cost":1}'

Response

200
{ "start" : "http://localhost:7474/db/data/node/123",
  "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/341", "http://localhost:7474/db/data/node/456" ],
  "length" : 2,
  "relationships" : [ "http://localhost:7474/db/data/relationship/564", "http://localhost:7474/db/data/relationship/32" ],
  "end" : "http://localhost:7474/db/data/node/456"
}

Results from "dijkstra" algorithm will also have "weight".

404: No path found using current algorithm and parameters

Finding paths between two nodes

POST /node/123/paths

{ "to": "http://localhost:7474/db/data/node/456",
  "relationships": {"type": "KNOWS", "direction": "out"},
  "max depth": 3,
  "algorithm", "shortestPath"
}

The "algorithm" parameter should match the name of the corresponding method in GraphAlgoFactory. Currently supported algos are: shortestPath, allPaths, allSimplePaths and dijkstra. More will be supported later on.

Example using curl

curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/paths -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"shortestPath"}'
curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/paths -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"dijkstra","cost property":"cost","default cost":1}'

Response

200
[ {
  "start" : "http://localhost:7474/db/data/node/123",
  "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/341", "http://localhost:7474/db/data/node/456" ],
  "length" : 2,
  "relationships" : [ "http://localhost:7474/db/data/relationship/564", "http://localhost:7474/db/data/relationship/32" ],
  "end" : "http://localhost:7474/db/data/node/456"
}, {
  "start" : "http://localhost:7474/db/data/node/123",
  "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/41", "http://localhost:7474/db/data/node/456" ],
  "length" : 2,
  "relationships" : [ "http://localhost:7474/db/data/relationship/437", "http://localhost:7474/db/data/relationship/97" ],
  "end" : "http://localhost:7474/db/data/node/456"
} ]

Results from "dijkstra" algorithm will also have "weight".

204: No path found using current algorithm and parameters