GraphDB REST API cURL Commands¶

What’s in this document?

Cluster group management
Cluster monitoring
Data import
Infrastructure monitoring
Location management
Repository management
Repository monitoring
Saved queries
Security management
SPARQL template management
SQL views management
Authentication
Structures monitoring

This page displays GraphDB REST API calls as cURL commands, which enables developers to script these calls in their applications.

See also the Help ‣ REST API view of the GraphDB Workbench where you will find a complete reference of all REST APIs and be able to run API calls directly from the browser.

In addition to this, the RDF4J API is also available.

Cluster group management ¶

Get cluster config

GET /rest/cluster/config

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/config'

Get cluster group status

GET /rest/cluster/group/status

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/group/status'

Get cluster node status

GET /rest/cluster/node/status

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/node/status'

Create cluster group

POST /rest/cluster/config

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "electionMinTimeout": 7000,
   "electionRangeTimeout": 5000,
   "heartbeatInterval": 2000,
   "messageSizeKB": 64,
   "nodes": [
     "string"
   ],
   "verificationTimeout": 1500
 }' '<base_url>/rest/cluster/config'

Add cluster node

POST /rest/cluster/config/node

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "nodes": [
     "string"
   ]
 }' '<base_url>/rest/cluster/config/node'

Update cluster group properties

PATCH /rest/cluster/config

Example:

curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "electionMinTimeout": 7000,
   "electionRangeTimeout": 5000,
   "heartbeatInterval": 2000,
   "messageSizeKB": 64,
   "verificationTimeout": 1500
 }' '<base_url>/rest/cluster/config'

Delete cluster group

DELETE /rest/cluster/config

Example:

curl -X DELETE --header 'Accept: application/json' '<base_url>/rest/cluster/config?force=false'

Delete cluster node

DELETE /rest/cluster/config/node

Example:

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "nodes": [
     "string"
   ]
 }' '<base_url>/rest/cluster/config/node'

Cluster monitoring ¶

Get cluster statistics

GET /rest/monitor/cluster

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/cluster'

Data import ¶

Most data import queries can either take the following set of attributes as an argument or return them as a response.

fileNames (string list): A list of filenames that are to be imported.
importSettings (JSON object): Import settings.
- baseURI (string): Base URI for the files to be imported.
- context (string): Context for the files to be imported.
- data (string): Inline data.
- forceSerial (boolean): Force use of the serial statements pipeline.
- name (string): Filename.
- status (string): Status of an import - pending, importing, done, error, none, interrupting.
- timestamp (integer): When was the import started.
- type (string): The type of the import.
- replaceGraphs (string list): A list of graphs that you want to be completely replaced by the import.
- parserSettings (JSON object): Parser settings.
  - failOnUnknownDataTypes (boolean): Fail parsing if datatypes are not recognized.
  - failOnUnknownLanguageTags (boolean): Fail parsing if languages are not recognized.
  - normalizeDataTypeValues (boolean): Normalize recognized datatypes values.
  - normalizeLanguageTags (boolean): Normalize recognized language tags.
  - preserveBNodeIds (boolean): Use blank node IDs found in the file instead of assigning them.
  - stopOnError (boolean): Stop on error. If false, the error will be logged and parsing will continue.
  - verifyDataTypeValues (boolean): Verify recognized datatypes.
  - verifyLanguageTags (boolean): Verify language based on a given set of definitions for valid languages.

Cancel server file import operation

DELETE /rest/repositories/<repo_id>/import/server

Example:

curl -X DELETE <base_url>/rest/repositories/<repo-id>/import/server?name=<encoded_filepath>

Get server files available for import

GET /rest/repositories/<repo_id>/import/server

Example:

curl <base_url>/rest/repositories/<repo_id>/import/server

Import a server file into the repository

POST /rest/repositories/<repo_id>/import/server

Example:

curl -X POST --header 'Content-Type: application/json' -d '{
  "fileNames": [
    "<data_url>",
    "<data_url>"
  ]
}' <base_url>/rest/repositories/<repo_id>/import/server

Hint

Common parameters:

<base_url>: The URL host and path leading to the deployed GraphDB Workbench webapp;

<repo_id>: The id string with which the current repository can be referred to;

<encoded_filepath>: Encoded filepath leading to a server file that is in the process of being imported.

Infrastructure monitoring ¶

Get all infrastructure statistics

GET /rest/monitor/infrastructure

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/infrastructure'

Location management ¶

Most location management queries can either take the following set of attributes as an argument or return them as a response.

active (boolean): True if the location is the currently active one – the local location is the only location that can be active at any given point.
defaultRepository (string): Default repository for the location.
errorMsg (string): Error message, if there was an error connecting to this location.
label (string): Human readable label
local (boolean): True if the location is local (on the same machine as the Workbench).
password (string): Password for the new location if any. This parameter only makes sense for remote locations.
system (boolean): True if the location is the system location.
uri (string): The GraphDB location URL.
username (string): Username for the new location if any. This parameter only makes sense for remote locations.

Get all connected GraphDB locations

GET /rest/locations

Example:

curl <base_url>/rest/locations

Modify settings for a connected GraphDB location

POST /rest/locations

Example:

curl -X POST <base_url>/rest/locations -H 'Content-Type: application/json' -d '
    {
        "username": "<username>",
        "password": "<password>",
        "uri": "<location_uri>"
    }'

Connect to a remote GraphDB location

PUT /rest/locations

Example:

curl -X PUT <base_url>/rest/locations -H 'Content-Type: application/json' -d '
    {
        "username": "<username>",
        "password": "<password>",
        "uri": "<location_uri>"
    }'

Disconnect a GraphDB location

DELETE /rest/locations

Example:

curl -X DELETE <base_url>/rest/locations?uri=<encoded_location_uri>

Set the default repository

POST /rest/locations/active/default-repository

Example:

curl -X POST <base_url>/rest/locations/active/default-repository -H 'Content-Type: application/json' -d '
{
    "repository": "<repo_id>"
}'

Repository management ¶

Most repository management queries can either take the following set of attributes as an argument or return them as a response.

externalUrl (string): The URL that the repository can be accessed at by an external service.
id (string): The repository id.
local (boolean): True if the repository is local (on the same machine as the Workbench).
location (string): If remote, the repository’s location.
title (string): The repository title.
type (string): Repository type - worker, master or system.
unsupported (boolean): True if the repository is unsupported.
writable (boolean): True if the repository is writable.
readable (boolean): True if the repository is readable.
uri (string): The GraphDB location URL.

Get all repositories in the current or another location

GET /rest/repositories

Example:

curl <base_url>/rest/repositories

Get repository configuration as Turtle

GET /rest/repositories/<repo_id>

Example:

curl <base_url>/rest/repositories/<repo_id>?location=<encoded_location_uri>

Get repository size

GET /rest/repositories/<repo_id>/size

Example:

curl <base_url>/rest/repositories/<repo_id>/size?location=<encoded_location_uri>

Create a repository in an attached GraphDB location (.ttl file)

POST /rest/repositories

Example:

curl -X POST <base_url>/rest/repositories?location=<encoded_location_uri> -H 'Content-Type: multipart/form-data' -F config=@<repo_ttl_config_filename>

Restart a repository

POST /rest/repositories/<repo_id>/restart

Example:

curl -X POST <base_url>/rest/repositories/<repo_id>/restart

Edit repository configuration

PUT /rest/repositories/<repo_id>

Example:

curl -X PUT <base_url>/rest/repositories/<repo_id> -H 'Accept: application/json' -H 'Content-Type: application/json' -d '
    {
        "id": "<repo_id>",
        "location": "<location_uri>",
        "title": "<repo_title>",
        "type": "graphdb",
        "sesameType":"graphdb:SailRepository",
        "params":{
            "queryTimeout":{
                "name":"queryTimeout",
                "label":"Query timeout (seconds)",
                "value":"0"
            },
            "cacheSelectNodes":{
                "name":"cacheSelectNodes",
                "label":"Cache select nodes",
                "value":"true"
            },
            "rdfsSubClassReasoning":{
                "name":"rdfsSubClassReasoning",
                "label":"RDFS subClass reasoning",
                "value":"true"
            },
            "validationEnabled":{
                "name":"validationEnabled",
                "label":"Enable the SHACL validation",
                "value":"true"
            },
            "ftsStringLiteralsIndex":{
                "name":"ftsStringLiteralsIndex",
                "label":"FTS index for xsd:string literals",
                "value":"default"
            },
            "shapesGraph":{
                "name":"shapesGraph",
                "label":"Named graphs for SHACL shapes",
                "value":"http://rdf4j.org/schema/rdf4j#SHACLShapeGraph"
            },
            "parallelValidation":{
                "name":"parallelValidation",
                "label":"Run parallel validation",
                "value":"true"
            },
            "checkForInconsistencies":{
                "name":"checkForInconsistencies",
                "label":"Enable consistency checks",
                "value":"false"
            },
            "performanceLogging":{
                "name":"performanceLogging",
                "label":"Log the execution time per shape",
                "value":"false"
            },
            "disableSameAs":{
                "name":"disableSameAs",
                "label":"Disable owl:sameAs",
                "value":"true"
            },
            "ftsIrisIndex":{
                "name":"ftsIrisIndex",
                "label":"FTS index for full-text indexing of IRIs",
                "value":"en"
            },
            "entityIndexSize":{
                "name":"entityIndexSize",
                "label":"Entity index size",
                "value":"10000000"
            },
            "dashDataShapes":{
                "name":"dashDataShapes",
                "label":"DASH data shapes extensions",
                "value":"true"
            },
            "queryLimitResults":{
                "name":"queryLimitResults",
                "label":"Limit query results",
                "value":"0"
            },
            "throwQueryEvaluationExceptionOnTimeout":{
                "name":"throwQueryEvaluationExceptionOnTimeout",
                "label":"Throw exception on query timeout",
                "value":"false"
            },
            "member":{
                "name":"member",
                "label":"FedX repo members",
                "value":[]
            },
            "storageFolder":{
                "name":"storageFolder",
                "label":"Storage folder",
                "value":"storage"
            },
            "validationResultsLimitPerConstraint":{
                "name":"validationResultsLimitPerConstraint",
                "label":"Validation results limit per constraint",
                "value":"1000"
            },
            "enablePredicateList":{
                "name":"enablePredicateList",
                "label":"Enable predicate list index",
                "value":"true"
            },
            "transactionalValidationLimit":{
                "name":"transactionalValidationLimit",
                "label":"Transactional validation limit",
                "value":"500000"
            },
            "ftsIndexes":{
                "name":"ftsIndexes",
                "label":"FTS indexes to build (comma delimited)",
                "value":"default, iri, en"
            },
            "logValidationPlans":{
                "name":"logValidationPlans",
                "label":"Log the executed validation plans",
                "value":"false"
            },
            "imports":{
                "name":"imports",
                "label":"Imported RDF files('\'';'\'' delimited)",
                "value":""
            },
            "isShacl":{
                "name":"isShacl",
                "label":"Enable SHACL validation",
                "value":"false"
            },
            "inMemoryLiteralProperties":{
                "name":"inMemoryLiteralProperties",
                "label":"Cache literal language tags",
                "value":"true"
            },
            "ruleset":{
                "name":"ruleset",
                "label":"Ruleset",
                "value":"rdfsplus-optimized"
            },
            "readOnly":{
                "name":"readOnly",
                "label":"Read-only",
                "value":"false"
            },
            "enableLiteralIndex":{
                "name":"enableLiteralIndex",
                "label":"Enable literal index",
                "value":"true"
            },
            "enableFtsIndex":{
                "name":"enableFtsIndex",
                "label":"Enable full-text search (FTS) index",
                "value":"false"
            },
            "defaultNS":{
                "name":"defaultNS",
                "label":"Default namespaces for imports('\'';'\'' delimited)",
                "value":""
            },
            "enableContextIndex":{
                "name":"enableContextIndex",
                "label":"Enable context index",
                "value":"false"
            },
            "baseURL":{
                "name":"baseURL",
                "label":"Base URL",
                "value":"http://example.org/owlim#"
            },
            "logValidationViolations":{
                "name":"logValidationViolations",
                "label":"Log validation violations",
                "value":"false"
            },
            "globalLogValidationExecution":{
                "name":"globalLogValidationExecution",
                "label":"Log every execution step of the SHACL validation",
                "value":"false"
            },
            "entityIdSize":{
                "name":"entityIdSize",
                "label":"Entity ID size",
                "value":"32"
            },
            "repositoryType":{
                "name":"repositoryType",
                "label":"Repository type",
                "value":"file-repository"
            },
            "eclipseRdf4jShaclExtensions":{
                "name":"eclipseRdf4jShaclExtensions",
                "label":"RDF4J SHACL extensions",
                "value":"true"
            },
            "validationResultsLimitTotal":{
                "name":"validationResultsLimitTotal",
                "label":"Validation results limit total",
                "value":"1000000"}
            }
        }
    }'

Hint

Adjust parameters with new values except for <repo_id> in order to edit the current repository configuration.

Delete a repository in an attached GraphDB location

DELETE /rest/repositories/<repo_id>

Example:

curl -X DELETE <base_url>/rest/repositories/<repo_id>?location=<encoded_location_uri>

Hint

Common parameters:

<base_url>: The URL host and path leading to the deployed GDB Workbench web app;

<location_uri>: File system path of the physical location of the repo (could be local or remote);

<encoded_location_uri>: URL encoded file system path of the physical location of the repo (could be local or remote);

<repo_id>: The id string with which the current repository can be referred to;

<repo_title>: Human-readable name of the current repository;

<repo_type>: Type of the repository, could be se, worker, master.

Repository monitoring ¶

Get repository statistics

GET /rest/monitor/repository/{repositoryID}

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/repository/<repo_id>'

Saved queries ¶

Get saved query (or queries, if no parameter specified)

GET /rest/sparql/saved-queries

Example:

curl <base_url>/rest/sparql/saved-queries?name=<query_name>

Create a new saved query

POST /rest/sparql/saved-queries

Example:

curl -X POST <base_url>/rest/sparql/saved-queries -H 'Content-Type: application/json' -d '
{
    "body": "<query_body>",
    "name": "<query_name>"
}'

Edit an existing saved query

PUT /rest/sparql/saved-queries

Example:

curl -X PUT <base_url>/rest/sparql/saved-queries -H 'Content-Type: application/json' -d '
{
    "body": "<query_body>",
    "name": "<query_name>"
}'

Delete an existing saved query

DELETE /rest/sparql/saved-queries

Example:

curl -X DELETE <base_url>/rest/sparql/saved-queries?name=<query_name>

Security management ¶

Check if security is enabled

GET /rest/security

Example:

curl <base_url>/rest/security

Enable security

POST /rest/security

Example:

curl -X POST --header 'Content-Type: application/json' -d true <base_url>/rest/security

Check if free access is enabled

GET /rest/security/free-access

curl <base_url>/rest/security/free-access

Enable or disable free access

POST /rest/security/free-access

Example:

curl -X POST --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "authorities": ["string"],
        "enabled": boolean
    }'  '<base_url>/rest/security/free-access'

Get all users

GET /rest/security/users

Example:

curl <base_url>/rest/security/users

Get a user

GET /rest/security/users/<username>

Example:

curl <base_url>/rest/security/users/<username>

Delete a user

DELETE /rest/security/users/<username>

Example:

curl -X DELETE <base_url>/rest/security/users/<username>

Change settings for a user

PATCH /rest/security/users/<username>

Example:

curl -X PATCH --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "password": "string"
   }'   '<base_url>/rest/security/users/<username>'

Create a user

POST /rest/security/users/<username>

Example:

curl -X POST --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "grantedAuthorities": ["string"],
        "username": "string",
        "password": "string"
    }'  '<base_url>/rest/security/users/<username>'

Edit a user

PUT /rest/security/users/<username>

Example:

curl -X PUT --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "grantedAuthorities": ["string"],
        "username": "string",
        "password": "string"
    }'  '<base_url>/rest/security/users/<username>'

SPARQL template management ¶

Create, edit, delete, and execute SPARQL templates, as well as to view all templates and their configuration.

Get IDs of all configured SPARQL templates per current repository

GET /rest/repositories/<repo_id>/sparql-templates

Example:

curl '<base_url>/rest/repositories/<repo_id>/sparql-templates'

Get a SPARQL template configuration

GET /rest/repositories/<repo_id>/sparql-templates/configuration

Example:

curl -X GET --header 'Accept: text/plain' '<base_url>/rest/repositories/<repo_id>/sparql-templates/configuration?templateID=<template_id>'

Create a new SPARQL template

POST /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: */*' -d '{
    "query": "<update_query_string> }",
    "templateID": "<template_id>"
}' '<base_url>/rest/repositories/<repo_id>/sparql-templates'

Delete an existing SPARQL template

DELETE /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X DELETE --header 'Accept: */*' '<base_url>/rest/repositories/<repo_id>/sparql-templates?templateID=<template_id>'

Edit an existing SPARQL template

PUT /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X PUT --header 'Content-Type: text/plain' --header 'Accept: */*' -d '<update query_string> ' '<base_url>/rest/repositories/<repo_id>/sparql-templates?templateID=<template_id>'

Execute an existing SPARQL template

POST /rest/repositories/<repo_id>/sparql-templates/execute

Example (based on this data):

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
     "sugar" : "none" ,
     "year" : 2020 ,
     "s" : "http://www.ontotext.com/example/wine#Blanquito"
 }' '<base_url>/rest/repositories/<repo_id>/sparql-templates/execute'

SQL views management ¶

Access, create, and edit SQL views (tables), as well as delete existing saved queries and see all SQL views for the active repository.

Get all SQL view names for current repository

GET /rest/sql-views/tables

Example:

curl -X GET --header 'Accept: application/json' --header 'X-GraphDB-Repository: <repoID>' '<base_url>/rest/sql-views/tables'

Get a SQL view configuration

GET /rest/sql-views/tables/<name>

Example:

curl -X GET --header 'Accept: application/json' --header 'X-GraphDB-Repository: <repoID>' '<base_url>/rest/sql-views/tables/<name>'

Create a new SQL view

POST /rest/sql-views/tables/

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: */*' --header 'X-GraphDB-Repository:<repoID> -d '{
    "name": "string",
    "query": "string",
    "columns": ["string"]
    }'
    <base_url>/rest/sql-views/tables/

Edit an existing SQL view

PUT /rest/sql-views/tables/<name>

Example:

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: */*' --header 'X-GraphDB-Repository:<repoID>' -d '{
    "name": "string",
    "query": "string",
    "columns": ["string"]
    }'
    <base_url>/rest/sql-views/tables/<name>

Delete an existing saved query

DELETE /rest/sql-views/tables/<name>

Example:

curl -X DELETE <base_url>/rest/sql-views/tables/<name>

Authentication ¶

Obtain a GDB token in exchange for username and password

POST /rest/login/**

Example:

curl <base_url>/rest/login/<username> -X POST -H 'X-GraphDB-Password: <password>'

This command will return the user’s roles and GraphDB applications settings. It will also generate a GDB token, which is returned in an Authorization header and will be used at every next authentication request.

Structures monitoring ¶

Get structures statistics

GET /rest/monitor/structures

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/structures'