OpenAPI Specification
openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Graphs API
version: 3.12.10 (API v0)
description: Manage named graphs and query edges
tags:
- description: Manage named graphs and query edges
name: Graphs
paths:
/_db/{database-name}/_api/edges/{collection}:
get:
description: 'Returns an array of edges starting or ending in the node identified by
`vertex`.
'
operationId: getVertexEdges
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The name of the edge collection you want to retrieve edges from.
'
in: path
name: collection
required: true
schema:
type: string
- description: 'The document identifier of the start node.
'
in: query
name: vertex
required: true
schema:
type: string
- description: '- `"in"`: Return edges that reference the `vertex` in the `_to` attribute.
- `"out"`: Return edges that reference the `vertex` in the `_from` attribute.
- `"any"`: Return edges that reference the `vertex` in the `_from` or `_to` attribute.
'
in: query
name: direction
required: false
schema:
default: any
enum:
- any
- in
- out
type: string
- description: 'Set this header to `true` to allow the Coordinator to ask any shard replica for
the data, not only the shard leader. This may result in "dirty reads".
'
in: header
name: x-arango-allow-dirty-read
required: false
schema:
type: boolean
responses:
'200':
description: 'is returned if the edge collection was found and edges were retrieved.
'
'400':
description: 'is returned if the request contains invalid parameters.
'
'404':
description: 'is returned if the edge collection was not found.
'
summary: Get inbound and outbound edges
tags:
- Graphs
/_db/{database-name}/_api/gharial:
get:
description: 'Lists all graphs stored in this database.
'
operationId: listGraphs
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
graphs:
description: 'A list of all named graphs.
'
items:
properties:
graph:
description: 'The properties of the named graph.
'
properties:
_id:
description: 'The internal id value of this graph.
'
type: string
_rev:
description: 'The revision of this graph. Can be used to make sure to not override
concurrent modifications to this graph.
'
type: string
edgeDefinitions:
description: 'An array of definitions for the relations of the graph.
Each has the following type:
'
items:
properties:
collection:
description: 'Name of the edge collection, where the edges are stored in.
'
type: string
from:
description: 'List of node collection names.
Edges in collection can only be inserted if their _from is in any of the collections here.
'
items:
type: string
type: array
to:
description: 'List of node collection names.
Edges in collection can only be inserted if their _to is in any of the collections here.
'
items:
type: string
type: array
required:
- collection
- from
- to
type: object
type: array
isDisjoint:
description: 'Whether the graph is a Disjoint SmartGraph.
'
type: boolean
isSatellite:
description: 'Whether the graph is a SatelliteGraph.
'
type: boolean
isSmart:
description: 'Whether the graph is a SmartGraph (`smartGraphAttribute` is set)
or EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).
'
type: boolean
name:
description: 'The name of the graph.
'
type: string
numberOfShards:
description: 'Number of shards created for every new collection in the graph.
'
type: integer
orphanCollections:
description: 'An array of additional node collections.
Documents in these collections do not have edges within this graph.
'
items:
type: string
type: array
replicationFactor:
description: 'The replication factor used for every new collection in the graph.
For SatelliteGraphs, it is the string `"satellite"`.
Default: The `replicationFactor` defined by the database.
'
type: integer
smartGraphAttribute:
description: 'Name of the sharding attribute in the SmartGraph case.
'
type: string
writeConcern:
description: 'The default write concern for new collections in the graph.
It determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
`writeConcern` cannot be greater than `replicationFactor`.
For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the
number of DB-Servers and the attribute is not available. _(cluster only)_
'
type: integer
required:
- name
- edgeDefinitions
- orphanCollections
- numberOfShards
- _id
- _rev
- replicationFactor
- isSmart
- isDisjoint
- isSatellite
type: object
type: object
type: array
required:
- error
- code
- graphs
type: object
description: 'Is returned if the module is available and the graphs can be listed.
'
summary: List all graphs
tags:
- Graphs
post:
description: 'The creation of a graph requires the name of the graph and a
definition of its edges.
'
operationId: createGraph
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Define if the request should wait until everything is synced to disk.
Changes the success HTTP response status code.
'
in: query
name: waitForSync
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
properties:
edgeDefinitions:
description: 'An array of definitions for the relations of the graph.
Each has the following type:
'
items:
properties:
collection:
description: 'Name of the edge collection, where the edges are stored in.
'
type: string
from:
description: 'A list of node collection names.
Edges you later insert into `collection` can only reference nodes
from these collections in their `_from` attribute (if you use the
interface for named graphs).
'
items:
type: string
type: array
to:
description: 'A list of node collection names.
Edges you later insert into `collection` can only reference nodes
from these collections in their `_to` attribute (if you use the
interface for named graphs).
'
items:
type: string
type: array
required:
- collection
- from
- to
type: object
type: array
isDisjoint:
default: false
description: 'Whether to create a Disjoint SmartGraph instead of a regular SmartGraph.
'
type: boolean
isSmart:
default: false
description: 'Define if the created graph should be smart.
- Setting `options.smartGraphAttribute` creates a SmartGraph (`isSmart` is automatically `true`).
- Setting `isSmart` to `true` but no `options.smartGraphAttribute` creates an EnterpriseGraph.
'
type: boolean
name:
description: 'Name of the graph.
'
type: string
options:
description: 'Options for creating collections within this graph.
It can contain the following attributes:
'
properties:
numberOfShards:
default: 1
description: 'The number of shards that is used for every collection within this graph.
Cannot be modified later.
'
type: integer
replicationFactor:
description: 'The replication factor used when initially creating collections for this graph.
Can be set to `"satellite"` to create a SatelliteGraph, which then ignores
`numberOfShards`, `minReplicationFactor`, and `writeConcern`.
Default: The `replicationFactor` defined by the database.
'
type: integer
satellites:
description: 'An array of collection names that is used to create SatelliteCollections
for a (Disjoint) SmartGraph using SatelliteCollections.
Each array element must be a string and a valid collection name.
The collection type cannot be modified later.
'
items:
type: string
type: array
smartGraphAttribute:
description: 'Setting this option creates a SmartGraph.
The attribute name that is used to smartly shard the nodes of a graph.
Every node in this SmartGraph has to have this attribute.
Cannot be modified later.
'
type: string
writeConcern:
description: 'Write concern for new collections in the graph.
It determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
`writeConcern` cannot be greater than `replicationFactor`.
For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the
number of DB-Servers and the attribute is not available. _(cluster only)_
'
type: integer
type: object
orphanCollections:
description: 'An array of additional node collections.
Documents in these collections do not have edges within this graph.
'
items:
type: string
type: array
required:
- name
type: object
responses:
'201':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 201
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
graph:
description: 'The information about the newly created graph.
'
properties:
_id:
description: 'The internal id value of this graph.
'
type: string
_rev:
description: 'The revision of this graph. Can be used to make sure to not override
concurrent modifications to this graph.
'
type: string
edgeDefinitions:
description: 'An array of definitions for the relations of the graph.
Each has the following type:
'
items:
properties:
collection:
description: 'Name of the edge collection, where the edges are stored in.
'
type: string
from:
description: 'List of node collection names.
Edges in collection can only be inserted if their _from is in any of the collections here.
'
items:
type: string
type: array
to:
description: 'List of node collection names.
Edges in collection can only be inserted if their _to is in any of the collections here.
'
items:
type: string
type: array
required:
- collection
- from
- to
type: object
type: array
isDisjoint:
description: 'Whether the graph is a Disjoint SmartGraph.
'
type: boolean
isSatellite:
description: 'Whether the graph is a SatelliteGraph.
'
type: boolean
isSmart:
description: 'Whether the graph is a SmartGraph (`smartGraphAttribute` is set)
or EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).
'
type: boolean
name:
description: 'The name of the graph.
'
type: string
numberOfShards:
description: 'Number of shards created for every new collection in the graph.
'
type: integer
orphanCollections:
description: 'An array of additional node collections.
Documents in these collections do not have edges within this graph.
'
items:
type: string
type: array
replicationFactor:
description: 'The replication factor used for every new collection in the graph.
For SatelliteGraphs, it is the string `"satellite"`.
'
type: integer
smartGraphAttribute:
description: 'Name of the sharding attribute in the SmartGraph case.
'
type: string
writeConcern:
description: 'The default write concern for new collections in the graph.
It determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
`writeConcern` cannot be greater than `replicationFactor`.
For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the
number of DB-Servers and the attribute is not available. _(cluster only)_
'
type: integer
required:
- name
- edgeDefinitions
- orphanCollections
- numberOfShards
- _id
- _rev
- replicationFactor
- isSmart
- isDisjoint
- isSatellite
type: object
required:
- error
- code
- graph
type: object
description: 'Is returned if the graph can be created and `waitForSync` is enabled
for the `_graphs` collection, or given in the request.
The response body contains the graph configuration that has been stored.
'
'202':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 202
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
graph:
description: 'The information about the newly created graph.
'
properties:
_id:
description: 'The internal id value of this graph.
'
type: string
_rev:
description: 'The revision of this graph. Can be used to make sure to not override
concurrent modifications to this graph.
'
type: string
edgeDefinitions:
description: 'An array of definitions for the relations of the graph.
Each has the following type:
'
items:
properties:
collection:
description: 'Name of the edge collection, where the edges are stored in.
'
type: string
from:
description: 'List of node collection names.
Edges in collection can only be inserted if their _from is in any of the collections here.
'
items:
type: string
type: array
to:
description: 'List of node collection names.
Edges in collection can only be inserted if their _to is in any of the collections here.
'
items:
type: string
type: array
required:
- collection
- from
- to
type: object
type: array
isDisjoint:
description: 'Whether the graph is a Disjoint SmartGraph.
'
type: boolean
isSatellite:
description: 'Whether the graph is a SatelliteGraph.
'
type: boolean
isSmart:
description: 'Whether the graph is a SmartGraph (`smartGraphAttribute` is set)
or EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).
'
type: boolean
name:
description: 'The name of the graph.
'
type: string
numberOfShards:
description: 'Number of shards created for every new collection in the graph.
'
type: integer
orphanCollections:
description: 'An array of additional node collections.
Documents in these collections do not have edges within this graph.
'
items:
type: string
type: array
replicationFactor:
description: 'The replication factor used for every new collection in the graph.
For SatelliteGraphs, it is the string `"satellite"`.
'
type: integer
smartGraphAttribute:
description: 'Name of the sharding attribute in the SmartGraph case.
'
type: string
writeConcern:
description: 'The default write concern for new collections in the graph.
It determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
`writeConcern` cannot be greater than `replicationFactor`.
For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the
number of DB-Servers and the attribute is not available. _(cluster only)_
'
type: integer
required:
- name
- edgeDefinitions
- orphanCollections
- numberOfShards
- _id
- _rev
- replicationFactor
- isSmart
- isDisjoint
- isSatellite
type: object
required:
- error
- code
- graph
type: object
description: 'Is returned if the graph can be created and `waitForSync` is disabled
for the `_graphs` collection and not given in the request.
The response body contains the graph configuration that has been stored.
'
'400':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 400
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if the request is in a wrong format.
'
'403':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 403
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if your user has insufficient rights.
In order to create a graph, you need to have at least the following privileges:
- `Administrate` access on the database.
- `Read Only` access on every collection used within this graph.
'
'409':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 409
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if there is a conflict storing the graph. This can occur
either if a graph with this name already exists, or if there is an
edge definition with the same edge collection but different `from`
and `to` node collections in any other graph.
'
summary: Create a graph
tags:
- Graphs
/_db/{database-name}/_api/gharial/{graph}:
delete:
description: 'Drops an existing graph object by name.
Optionally all collections not used by other graphs
can be dropped as well.
'
operationId: deleteGraph
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The name of the graph.
'
in: path
name: graph
required: true
schema:
type: string
# --- truncated at 32 KB (263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-graphs-api-openapi.yml