GraphDB REST API cURL Commands

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'

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.

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>"
}'

Recovery management

Create, edit, and delete full or partial backups, and restore fully or partially a GraphDB instance from a backup.

Get all backups

GET /rest/recovery/backups

Example:

curl '<base_url>/rest/recovery/backups'

Get backup content

GET /rest/recovery/backups/<backup_name>

Example:

curl '<base_url>/rest/recovery/backups/<backup_name>'

Create a new backup of a GraphDB instance

POST /rest/recovery/backups/<backup_name>

Example:

• Full backup: backing up the entire data directory of the GraphDB instance with all repositories in it

  curl -X POST '<base_url>/rest/recovery/backups/<backup-name>'
  

• Partial backup: backing up only a certain repository(ies). This allows you to restore particular repositories or clean up the entire GraphDB instance and leave only backed up repositories.

  curl -X POST -H 'Content-Type: application/json' -d '{
    "repositories": [
       "<repository-name>"
    ]
  }' '<base_url>/rest/recovery/backups/<backup-name>?withSystemData=false'
  

  Hint

  If you want to back up more than one repository, include them in the command like so: "repositories": [ "<repo_name1>", "<repo_name2>" ], etc.

  Note

  If a POST request does not include a list of repositories for backup, it will automatically create a full backup.

Restore from a backup

POST /rest/recovery/restore/<backup_name>

Example:

• Full restore from a backup:

  curl -X POST -H 'Content-Type: application/json' '<base_url>/rest/recovery/restore/<backup-name>?cleanDataDir=true'
  

• Partial restore from a backup, meaning to restore only particular repositories from a full backup:

  curl -X POST -H 'Content-Type: application/json' -d '{
     "repositories": [
       "<repository-name>"
     ]
   }' '<base_url>/rest/recovery/restore/<backup-name>?cleanDataDir=false&withSystemData=false'
  

Note

When set to true, the cleanDataDir parameter clears the GraphDB data directory before applying a backup. It is false by default.

Update or create a backup

PUT /rest/recovery/backups/<backup_name>

Example:

• Full backup:

  curl -X PUT '<base_url>/rest/recovery/backups/<backup-name>'
  

• Partial backup:

  curl -X PUT -H 'Content-Type: application/json' -d '{
    "repositories": [
       "<repository-name>"
    ]
  }' '<base_url>/rest/recovery/backups/<backup-name>?withSystemData=false'
  

Note

If you do not want to use the settings.js (containing the settings of the instance located in the GraphDB data directory) and users.js files for creating a backup/restore, set the withSystemData parameter to false.

Delete a backup

DELETE /rest/recovery/backups/<backup_name>

Example:

curl -X DELETE '<base_url>/rest/recovery/backups/<backup-name>'

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.

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' --header 'Accept:  */*' -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' --header 'Accept: application/json' -d '
    {
        appSettings: {
            DEFAULT_SAMEAS: boolean
            DEFAULT_INFERENCE: boolean
            EXECUTE_COUNT: boolean
            IGNORE_SHARED_QUERIES: boolean
            },
        password: "<password>"
    }'
    <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"],
        pass: "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' --header 'Accept: text/plain' -d '
  {
      appSettings: {
          DEFAULT_SAMEAS: boolean
          DEFAULT_INFERENCE: boolean
          EXECUTE_COUNT: boolean
          IGNORE_SHARED_QUERIES: boolean
          },
      grantedAuthorities: ["string"],
      pass: "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.