Overview

This document describes the REST API of the Open Research Knowledge Graph.

This API is still in development and therefore unstable and subject to change! Be aware that the API can (and will) break without notice, so beware if you intend to consume it directly. We will support a stable API in the future, but it is uncertain when that will be. This documentation will be updated to reflect that.

HTTP verbs

The Open Research Knowledge Graph REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

The verbs PATCH, PUT, and DELETE are (currently) unsupported.

HTTP status codes

The Open Research Knowledge Graph REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

All responses with error codes that do not indicate success will contain a payload that describes the error. Their structure is documented in the section about Error representation.

Authentication (AuthN)

Authentication is done via the OAuth2 protocol. An authentication token needs to be obtained and provided to protected endpoints.

This endpoint only delivers information about the currenly logged in user. If you need to obtain information about other users in the system, check the Contributors section.

Obtaining an access token

A token can be obtained by sending a POST request to the /oauth/token endpoint. The client needs to provide its client ID and secret via basic authentication (base64-encoded). All request parameters need to be passed in application/x-www-form-urlencoded. The parameters are:

grant_type

Always password.

username

The email address of the user.

password

The password defined by the user.

The response will contain the access token and time of invalidation. Obtaining a new token is only possible by re-authenticating to the API.

Example:

curl -X POST --user 'orkg-client:secret' -d 'grant_type=password&username=user@example.org&password=password' http://localhost:8000/oauth/token

Command line users can save the token directly to a variable and use this in following requests. e.g.

export TOKEN=$(curl --silent -X POST --user 'orkg-client:secret' -d 'grant_type=password&username=user@example.org&password=password' http://localhost:8000/oauth/token | jq -r '.access_token')

Using the token

Tokens can be provided to the API via the Authorization header field with the bearer authentication type. Authorization will be performed on tokens only.

Example:

curl  -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/auth/user

Obtaining user information

User information about the currently logged-in user can be obtained from the /api/user/ endpoint via GET requests. An authentication token needs to be provided.

Other contributor information can be obtained individually from /api/user/{id}, where {id} is a UUID of the user. This will only provide selected properties for display purposes; currently the ID and the display name.

Changing user information

User information can be changed via a PUT request to the /api/user/ endpoint. An authentication token needs to be provided.

To change the user name, the display_name key needs to be present in the body.

Changing the password

Passwords can be changed via a PUT request to the /api/user/password endpoint. An authentication token needs to be provided.

To change the password, the current_password, new_password and new_matching_password keys need to be present in the body. The current_password must match the current password of the user. Additionally, new_password and new_matching_password need to contain the same values.

Registering a user

New user accounts can be registered via a POST request to the /api/auth/register endpoint.

The email, password and matching_password keys need to be provided in the request body. An optional name key can be provided to set the display name of the user (non-blank).

The endpoint will return the user data of the generated user.

Statements

A statement represents a kind of sentence in the knowledge graph, similar to RDF triples. Similar to a real sentence, it is a tuple of a subject, a predicate, and an object.

Subjects and objects represent nodes in the graph are formed from a resource. Objects can also be a literal value.

Predicates represent edges (relationships) in the graph.

Resources and predicates are identifiable by an ID, whereas literals are not since they represent a value.

Statements can also be referenced by their IDs. This allows storing and retrieving provenance information about them.

Listing statements

A GET request lists all the statements:

Curl request

$ curl 'http://localhost:8080/api/statements/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4512

{
  "content" : [ {
    "id" : "S326",
    "subject" : {
      "id" : "R243",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.978172Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P29",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:15.012199Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R244",
      "label" : "two",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.991549Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:15.08723Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S327",
    "subject" : {
      "id" : "R243",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.978172Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P30",
      "label" : "blub",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:15.020587Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R245",
      "label" : "three",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.999538Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:15.125065Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S328",
    "subject" : {
      "id" : "R243",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.978172Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P31",
      "label" : "to literal",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:15.028868Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "L95",
      "label" : "literal",
      "datatype" : "xsd:string",
      "_class" : "literal",
      "created_at" : "2023-09-25T15:45:15.008219Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "created_at" : "2023-09-25T15:45:15.202663Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 3,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 3,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Creating statements

A POST request creates a new statement. The response will be 201 Created when successful. The statement can be retrieved by following the URI in the Location header field.

The response body contains the created statement for convenience. This might be subject to change.

Creating statements can be done in two ways:

  1. For objects of type resource, send three IDs.

  2. For objects of type literal, send two IDs and the literal value in the body.

Creating statements with resource objects

Create a statement by submitting three IDs via POST:

Curl request
$ curl 'http://localhost:8080/api/statements/' -i -X POST \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "subject_id" : "R234",
  "predicate_id" : "P23",
  "object_id" : "R235"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/statements/
Content-Type: application/json
Content-Length: 1355

{
  "id" : "S318",
  "subject" : {
    "id" : "R234",
    "label" : "one",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:13.766382Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  },
  "predicate" : {
    "id" : "P23",
    "label" : "less than",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:45:13.798457Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  },
  "object" : {
    "id" : "R235",
    "label" : "two",
    "classes" : [ ],
    "shared" : 1,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:13.783146Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  },
  "created_at" : "2023-09-25T15:45:13.875898Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b"
}

Deleting a statement

Delete a statement by providing the ID of the statement via a DELETE call:

The response will be 204 No Content when successful.

Curl request

$ curl 'https://incubating.orkg.org/api/statements/S1' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 204 No Content

Fetching a statement

A GET request provides information about a statement.

Curl request

$ curl 'http://localhost:8080/api/statements/S322' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1350

{
  "id" : "S322",
  "subject" : {
    "id" : "R240",
    "label" : "one",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:14.446301Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  },
  "predicate" : {
    "id" : "P26",
    "label" : "blah",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:45:14.504853Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  },
  "object" : {
    "id" : "R241",
    "label" : "two",
    "classes" : [ ],
    "shared" : 1,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:14.473153Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  },
  "created_at" : "2023-09-25T15:45:14.628679Z",
  "created_by" : "00000000-0000-0000-0000-000000000000"
}

Lookup statements by subject

A GET request lists all the statements with a given subject:

Curl request

$ curl 'http://localhost:8080/api/statements/subject/R231' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3355

{
  "content" : [ {
    "id" : "S316",
    "subject" : {
      "id" : "R231",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.373422Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P21",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:13.395644Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R232",
      "label" : "two",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.382489Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:13.453162Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S317",
    "subject" : {
      "id" : "R231",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.373422Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P22",
      "label" : "blub",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:13.404792Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R233",
      "label" : "three",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.388728Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:13.497298Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Lookup statements by predicate

A GET request lists all the statements with a given predicate:

Curl request

$ curl 'http://localhost:8080/api/statements/predicate/P17' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3355

{
  "content" : [ {
    "id" : "S311",
    "subject" : {
      "id" : "R225",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:12.422566Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P17",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:12.451458Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R227",
      "label" : "three",
      "classes" : [ ],
      "shared" : 2,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:12.438742Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:12.641011Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S310",
    "subject" : {
      "id" : "R225",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:12.422566Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P17",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:12.451458Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R226",
      "label" : "two",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:12.431967Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:12.569963Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Fetching statements for a thing as a bundle

A GET request that fetches the entire subgraph of a certain entity and returns all the statements as a bundle.

A Bundle is a collection of statements that represents the sub-graph starting from a certain Thing in the KG.

When fetching a bundle of statements, filtering is possible via specifying certain parameters in the request. The number of levels in the tree being fetched can be filtered using the two query parameters minLevel & minLevel. Furthermore, to be able to further control which statements to fetch, a black/white listing operation can be introduced via the query parameters blacklist & whitelist - this filter applies to classes of subjects and objects of statements only -

The endpoint also provide the parameter includeFirst which by default is True meaning it will not apply black/white listing on first level.

Curl request

$ curl 'http://localhost:8080/api/statements/R236/bundle' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4361

{
  "root" : "R236",
  "statements" : [ {
    "id" : "S321",
    "subject" : {
      "id" : "R237",
      "label" : "two",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.999868Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P24",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:14.022015Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R239",
      "label" : "four",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.013563Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:14.198383Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S320",
    "subject" : {
      "id" : "R236",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.99341Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P25",
      "label" : "blub",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:14.035436Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R238",
      "label" : "three",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:14.007532Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:14.16029Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "S319",
    "subject" : {
      "id" : "R236",
      "label" : "one",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.99341Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P24",
      "label" : "blah",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T15:45:14.022015Z",
      "created_by" : "00000000-0000-0000-0000-000000000000"
    },
    "object" : {
      "id" : "R237",
      "label" : "two",
      "classes" : [ ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:13.999868Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T15:45:14.09827Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ]
}

Bulk Statements

Bulk operations on statements. Helps performing multiple calls together.

Fetch by Subjects

A GET request to get statements of multiple resources in the subject position.

Curl request

$ curl 'https://incubating.orkg.org/api/statements/subjects/?ids=R1,R3' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4241

[ {
  "id" : "R1",
  "statements" : {
    "content" : [ {
      "id" : "S1",
      "subject" : {
        "id" : "R1",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:46.561826Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "predicate" : {
        "id" : "P1",
        "label" : "some predicate label",
        "description" : null,
        "_class" : "predicate",
        "created_at" : "2023-09-25T08:38:46.561866Z",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
      },
      "object" : {
        "id" : "R2",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:46.561881Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "created_at" : "2023-09-25T08:38:46.56191Z",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true,
        "empty" : true
      },
      "pageNumber" : 0,
      "pageSize" : 5,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "totalElements" : 1,
    "totalPages" : 1,
    "last" : true,
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "number" : 0,
    "numberOfElements" : 1,
    "first" : true,
    "size" : 5,
    "empty" : false
  }
}, {
  "id" : "R3",
  "statements" : {
    "content" : [ {
      "id" : "S2",
      "subject" : {
        "id" : "R3",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:46.561925Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "predicate" : {
        "id" : "P2",
        "label" : "some predicate label",
        "description" : null,
        "_class" : "predicate",
        "created_at" : "2023-09-25T08:38:46.561937Z",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
      },
      "object" : {
        "id" : "R4",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:46.561946Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "created_at" : "2023-09-25T08:38:46.561961Z",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true,
        "empty" : true
      },
      "pageNumber" : 0,
      "pageSize" : 5,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "totalElements" : 1,
    "totalPages" : 1,
    "last" : true,
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "number" : 0,
    "numberOfElements" : 1,
    "first" : true,
    "size" : 5,
    "empty" : false
  }
} ]

Fetch by Objects

A GET request to get statements of multiple resources/literals in the object position.

Curl request

$ curl 'https://incubating.orkg.org/api/statements/objects/?ids=R2,R4' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4241

[ {
  "id" : "R2",
  "statements" : {
    "content" : [ {
      "id" : "S1",
      "subject" : {
        "id" : "R1",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:45.799919Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "predicate" : {
        "id" : "P1",
        "label" : "some predicate label",
        "description" : null,
        "_class" : "predicate",
        "created_at" : "2023-09-25T08:38:45.80067Z",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
      },
      "object" : {
        "id" : "R2",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:45.800798Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "created_at" : "2023-09-25T08:38:45.804718Z",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true,
        "empty" : true
      },
      "pageNumber" : 0,
      "pageSize" : 5,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "totalElements" : 1,
    "totalPages" : 1,
    "last" : true,
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "number" : 0,
    "numberOfElements" : 1,
    "first" : true,
    "size" : 5,
    "empty" : false
  }
}, {
  "id" : "R4",
  "statements" : {
    "content" : [ {
      "id" : "S2",
      "subject" : {
        "id" : "R3",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:45.804827Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "predicate" : {
        "id" : "P2",
        "label" : "some predicate label",
        "description" : null,
        "_class" : "predicate",
        "created_at" : "2023-09-25T08:38:45.804845Z",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
      },
      "object" : {
        "id" : "R4",
        "label" : "Default Label",
        "classes" : [ ],
        "shared" : 0,
        "featured" : false,
        "unlisted" : false,
        "verified" : false,
        "extraction_method" : "UNKNOWN",
        "_class" : "resource",
        "created_at" : "2023-09-25T08:38:45.804857Z",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "formatted_label" : null
      },
      "created_at" : "2023-09-25T08:38:45.804881Z",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
    } ],
    "pageable" : {
      "sort" : {
        "sorted" : false,
        "unsorted" : true,
        "empty" : true
      },
      "pageNumber" : 0,
      "pageSize" : 5,
      "offset" : 0,
      "paged" : true,
      "unpaged" : false
    },
    "totalElements" : 1,
    "totalPages" : 1,
    "last" : true,
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "number" : 0,
    "numberOfElements" : 1,
    "first" : true,
    "size" : 5,
    "empty" : false
  }
} ]

Edit Statements

A PUT request to edit multiple statements, with the same update body

Curl request

$ curl 'https://incubating.orkg.org/api/statements/?ids=S1,S2' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "predicate_id" : "P3",
  "object_id" : "R5"
}'

Response fields

Path Type Description

[].id

String

The statement id

[].statement

Object

The statement representation of the updated statement

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3009

[ {
  "id" : "S1",
  "statement" : {
    "id" : "S1",
    "subject" : {
      "id" : "R1",
      "label" : "Default Label",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:46.448742Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P3",
      "label" : "some predicate label",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T08:38:46.448979Z",
      "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
    },
    "object" : {
      "id" : "R5",
      "label" : "Default Label",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:46.448991Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T08:38:46.449012Z",
    "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
  }
}, {
  "id" : "S2",
  "statement" : {
    "id" : "S2",
    "subject" : {
      "id" : "R3",
      "label" : "Default Label",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:46.44892Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "predicate" : {
      "id" : "P3",
      "label" : "some predicate label",
      "description" : null,
      "_class" : "predicate",
      "created_at" : "2023-09-25T08:38:46.448979Z",
      "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c"
    },
    "object" : {
      "id" : "R5",
      "label" : "Default Label",
      "classes" : [ ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:46.448991Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "created_at" : "2023-09-25T08:38:46.449846Z",
    "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7"
  }
} ]

Delete Statements

A DELETE request to delete multiple statements simultaneously

Curl request

$ curl 'https://incubating.orkg.org/api/statements/?ids=S1,S2' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 204 No Content

Classes

Classes represent concepts in the knowledge graph. They can be attached to resources to indicate that the resource belongs to the respective class.

Listing classes

A GET request lists all classes:

Curl request

$ curl 'http://localhost:8080/api/classes/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 950

{
  "content" : [ {
    "id" : "C8",
    "label" : "programming language",
    "uri" : null,
    "description" : null,
    "_class" : "class",
    "created_at" : "2023-09-25T15:44:27.370024Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "C7",
    "label" : "research contribution",
    "uri" : null,
    "description" : null,
    "_class" : "class",
    "created_at" : "2023-09-25T15:44:27.364524Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Creating classes

A POST request creates a new class with a given label. An optional URI can be given to link to the class in an external ontology (RDF). The response will be 201 Created when successful. The class can be retrieved by following the URI in the Location header field.

The created class is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The class label

uri

String

The class URI

Curl request

$ curl 'http://localhost:8080/api/classes/' -i -X POST \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "foo",
  "uri" : "http://example.org/bar"
}'

HTTP response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/classes/C5
Content-Type: application/json
Content-Length: 223

{
  "id" : "C5",
  "label" : "foo",
  "uri" : "http://example.org/bar",
  "description" : null,
  "_class" : "class",
  "created_at" : "2023-09-25T15:44:27.012803Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The class ID

label

String

The class label

uri

String

An optional URI to describe the class (RDF)

created_at

String

The class creation datetime

created_by

String

The ID of the user that created the class. All zeros if unknown.

description

Null

The description of the class, if exists.

Fetching a class

A GET request provides information about a class.

Curl request

$ curl 'http://localhost:8080/api/classes/C6' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 221

{
  "id" : "C6",
  "label" : "research contribution",
  "uri" : null,
  "description" : null,
  "_class" : "class",
  "created_at" : "2023-09-25T15:44:27.229896Z",
  "created_by" : "00000000-0000-0000-0000-000000000000"
}

Lookup a class by label

Classes can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/classes/?q=research' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 944

{
  "content" : [ {
    "id" : "C3",
    "label" : "research topic",
    "uri" : null,
    "description" : null,
    "_class" : "class",
    "created_at" : "2023-09-25T15:44:25.902286Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "C1",
    "label" : "research contribution",
    "uri" : null,
    "description" : null,
    "_class" : "class",
    "created_at" : "2023-09-25T15:44:25.874061Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Lookup resources by class

List all resources that are of the provided class type

Curl request

$ curl 'http://localhost:8080/api/classes/C15/resources/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1481

{
  "content" : [ {
    "id" : "R128",
    "label" : "Contribution 2",
    "classes" : [ "C15" ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:44:28.455967Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  }, {
    "id" : "R127",
    "label" : "Contribution 1",
    "classes" : [ "C15" ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:44:28.394654Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Resources

Resources represent nodes in the knowledge graph. They can appear in the subject or object position in statements.

Listing resources

A GET request lists all resources:

Request parameters

Parameter Description

page

Page number of items to fetch (default: 1)

size

Number of items to fetch per page (default: 10)

sort

Key to sort by (default: not provided)

Curl request

$ curl 'http://localhost:8080/api/resources/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1480

{
  "content" : [ {
    "id" : "R19",
    "label" : "research contribution",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:11.193585Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  }, {
    "id" : "R20",
    "label" : "programming language",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:11.200018Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Creating resources

A POST request creates a new resource with a given label. An optional set of classes can be provided. The response will be 201 Created when successful. The resource can be retrieved by following the URI in the Location header field.

The created resource is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The resource label

Curl request

$ curl 'http://localhost:8080/api/resources/' -i -X POST \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "foo"
}'

HTTP response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/resources/R16
Content-Type: application/json
Content-Length: 454

{
  "id" : "R16",
  "label" : "foo",
  "classes" : [ ],
  "shared" : 0,
  "featured" : false,
  "unlisted" : false,
  "verified" : false,
  "extraction_method" : "UNKNOWN",
  "_class" : "resource",
  "created_at" : "2023-09-25T15:45:10.811104Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "formatted_label" : null
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The resource ID

label

String

The resource label

created_at

String

The resource creation datetime

created_by

String

The ID of the user that created the resource. All zeros if unknown.

classes

Array

The list of classes the resource belongs to

observatory_id

String

The ID of the observatory that maintains this resource.

extraction_method

String

Method to extract this resource. Can be one of "unknown", "manual" or "automatic".

organization_id

String

The ID of the organization that maintains this resource.

shared

Number

The number of times this resource is shared

_class

String

Class

formatted_label

Null

The formatted label of the resource if available

Editing a resource

A PUT request updates a resource with a new given label. The response will be 200 OK when successful. The created resource is returned in the body for convenience.

Curl request

$ curl 'http://localhost:8080/api/resources/R17' -i -X PUT \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "bar",
  "classes" : [ "C7" ]
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 458

{
  "id" : "R17",
  "label" : "bar",
  "classes" : [ "C7" ],
  "shared" : 0,
  "featured" : false,
  "unlisted" : false,
  "verified" : false,
  "extraction_method" : "UNKNOWN",
  "_class" : "resource",
  "created_at" : "2023-09-25T15:45:10.90847Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "formatted_label" : null
}

Fetching a resource

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/resources/R18' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 472

{
  "id" : "R18",
  "label" : "research contribution",
  "classes" : [ ],
  "shared" : 0,
  "featured" : false,
  "unlisted" : false,
  "verified" : false,
  "extraction_method" : "UNKNOWN",
  "_class" : "resource",
  "created_at" : "2023-09-25T15:45:11.108746Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "formatted_label" : null
}

Lookup a resource by label

Resources can be looked up by label by providing a search fragment.

Request parameters

Parameter Description

q

A search term that must be contained in the label

exact

Whether it is an exact string lookup or just containment

Curl request

$ curl 'http://localhost:8080/api/resources/?q=research' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1472

{
  "content" : [ {
    "id" : "R8",
    "label" : "research topic",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:09.934527Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  }, {
    "id" : "R6",
    "label" : "research contribution",
    "classes" : [ ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T15:45:09.921587Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Delete a resource

A DELETE request with the id of the resource to delete.

Note: This request is only acceptable if you have sufficient permissions.

a successful request return a No-Content HTTP status code.

Curl request

$ curl 'http://localhost:8080/api/resources/R1' -i -X DELETE \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 204 No Content

If the resource doesn’t exist, the API returns a 404 status code.

Curl request

$ curl 'http://localhost:8080/api/resources/NONEXISTENT' -i -X DELETE \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 186

{
  "status" : 404,
  "error" : "Not Found",
  "path" : "/api/resources/NONEXISTENT",
  "timestamp" : "2023-09-25T15:45:11.157439Z",
  "message" : "Resource \"NONEXISTENT\" not found."
}

To safely delete a resource, the resource shouldn’t have any statements related to it. In this case a Forbidden HTTP status is returned.

Curl request

$ curl 'http://localhost:8080/api/resources/R9' -i -X DELETE \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 220

{
  "status" : 403,
  "error" : "Forbidden",
  "path" : "/api/resources/R9",
  "timestamp" : "2023-09-25T15:45:10.342988Z",
  "message" : "Unable to delete resource \"R9\" because it is used in at least one statement."
}

Predicates

Predicates represent edges (relationships between nodes) in the knowledge graph. They consist of an ID and a label (for presentation). IDs always start with "P", followed by a number.

Listing predicates

A GET request lists all predicates:

Request parameters

Parameter Description

page

Page number of predicates to fetch (default: 1)

items

Number of predicates to fetch per page (default: 10)

sortBy

Key to sort by (default: not provided)

desc

Direction of the sorting (default: false)

Curl request

$ curl 'http://localhost:8080/api/predicates/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 896

{
  "content" : [ {
    "id" : "P10",
    "label" : "has name",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:44:56.498791Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "P11",
    "label" : "knows",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:44:56.502748Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination.

Creating predicates

A POST request creates a new predicate with a given label. The response will be 201 Created when successful. The predicate can be retrieved by following the URI in the Location header field.

The response body contains the created predicate for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The predicate label

Curl request

$ curl 'http://localhost:8080/api/predicates/' -i -X POST \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "knows"
}'

HTTP response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/predicates/P7
Content-Type: application/json
Content-Length: 193

{
  "id" : "P7",
  "label" : "knows",
  "description" : null,
  "_class" : "predicate",
  "created_at" : "2023-09-25T15:44:56.190106Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The predicate ID

label

String

The predicate label

created_at

String

The predicate creation datetime

created_by

String

The ID of the user that created the predicate. All zeros if unknown.

description

Null

The description of the predicate, if exists.

Editing a predicate

A PUT request updates a predicate with a new given label. The response will be 200 OK when successful. The created predicate is returned in the body for convenience.

Curl request

$ curl 'http://localhost:8080/api/predicates/P8' -i -X PUT \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "yaser"
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 192

{
  "id" : "P8",
  "label" : "yaser",
  "description" : null,
  "_class" : "predicate",
  "created_at" : "2023-09-25T15:44:56.25177Z",
  "created_by" : "00000000-0000-0000-0000-000000000000"
}

Fetching a predicate

A GET request provides information about a predicate.

Curl request

$ curl 'http://localhost:8080/api/predicates/P9' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 196

{
  "id" : "P9",
  "label" : "has name",
  "description" : null,
  "_class" : "predicate",
  "created_at" : "2023-09-25T15:44:56.441466Z",
  "created_by" : "00000000-0000-0000-0000-000000000000"
}

Lookup a predicate by label

Predicates can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/predicates/?q=name' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 901

{
  "content" : [ {
    "id" : "P4",
    "label" : "has name",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:44:55.975544Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "P5",
    "label" : "gave name to",
    "description" : null,
    "_class" : "predicate",
    "created_at" : "2023-09-25T15:44:55.980592Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Literals

Literals represent nodes in the knowledge graph. They can appear in the object position in statements.

Listing Literals

A GET request returns a paged list of literals. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/literals/' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1087

{
  "content" : [ {
    "id" : "L517",
    "label" : "R34fDDkl",
    "datatype" : "DUInPBycd",
    "_class" : "literal",
    "created_at" : "2022-10-30T11:13:10Z",
    "created_by" : "39770c7d-ebff-1363-d0e7-4855d78e5847"
  }, {
    "id" : "L387",
    "label" : "v8vr7G7",
    "datatype" : "O",
    "_class" : "literal",
    "created_at" : "2010-12-10T09:37:56Z",
    "created_by" : "7cff033a-8cb3-4856-9015-b7a935cd9dfb"
  }, {
    "id" : "L8",
    "label" : "kBtV1INPr",
    "datatype" : "hrNjuF",
    "_class" : "literal",
    "created_at" : "2013-11-02T01:37:21Z",
    "created_by" : "dc47c870-26e8-9c65-f430-341c65e7dae6"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 3,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 15,
  "totalPages" : 5,
  "last" : false,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 3,
  "first" : true,
  "size" : 3,
  "empty" : false
}

Creating Literals

A POST request creates a new literal with a given label (its value). The response will be 201 Created when successful. The resource can be retrieved by following the URI in the Location header field.

The created literal is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The updated value of the literal.

datatype

String

The updated datatype of the literal value.

Curl request

$ curl 'http://localhost:8080/api/literals/' -i -X POST \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "foo",
  "datatype" : "xs:foo"
}'

HTTP response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/literals/L69
Content-Type: application/json
Content-Length: 191

{
  "id" : "L69",
  "label" : "foo",
  "datatype" : "xs:foo",
  "_class" : "literal",
  "created_at" : "2023-09-25T15:44:50.833884Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The resource ID

label

String

The resource label

datatype

String

The data type of the literal value. Defaults to xsd:string.

created_at

String

The resource creation datetime

created_by

String

The ID of the user that created the literal. All zeros if unknown.

Editing a literal

A PUT request updates a literal with a new value through the label property. The response will be 200 OK when successful. The created literal is returned in the body for convenience.

Curl request

$ curl 'http://localhost:8080/api/literals/L70' -i -X PUT \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "bar",
  "datatype" : "dt:new"
}'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 191

{
  "id" : "L70",
  "label" : "bar",
  "datatype" : "dt:new",
  "_class" : "literal",
  "created_at" : "2023-09-25T15:44:50.883692Z",
  "created_by" : "00000000-0000-0000-0000-000000000000"
}

Fetching a literal

A GET request provides information about a literal.

Curl request

$ curl 'https://incubating.orkg.org/api/literals/L1234' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 220

{
  "id" : "L1234",
  "label" : "some literal value",
  "datatype" : "xsd:string",
  "_class" : "literal",
  "created_at" : "2023-06-01T15:19:04.778631092+02:00",
  "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1"
}

Lookup a literal by label

Literals can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/literals/?q=research' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 924

{
  "content" : [ {
    "id" : "L68",
    "label" : "research topic",
    "datatype" : "xsd:string",
    "_class" : "literal",
    "created_at" : "2023-09-25T15:44:50.628387Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  }, {
    "id" : "L66",
    "label" : "research contribution",
    "datatype" : "xsd:string",
    "_class" : "literal",
    "created_at" : "2023-09-25T15:44:50.619235Z",
    "created_by" : "00000000-0000-0000-0000-000000000000"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Lists

Lists represent an ordered collection of statements in the knowledge graph. Their elements are defined by statement using the "has list element" predicate and a special "index" property, indicating the position in the list. The elements of a list can only be modified using the dedicated list endpoints.

Creating lists

A POST request creates a new list with all the given parameters. The response will be 201 Created when successful. The list resource (object) can be retrieved by following the URI in the Location header field.

Request fields

Path Type Description

label

String

The label of the list.

elements

Array

The ids of the elements of the list.

Curl request

$ curl 'https://incubating.orkg.org/api/lists' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "List label",
  "elements" : [ "R1" ]
}'

The response body consists of the following fields:

The created list resource is returned in the body for convenience. This might be subject to change.

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/lists/R123
Content-Type: application/json
Content-Length: 196

{
  "id" : "R123",
  "label" : "List label",
  "elements" : [ "R1" ],
  "created_at" : "2023-09-25T08:38:53.142211Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "_class" : "list"
}

Fetching a list

A GET request provides information about a list.

Curl request

$ curl 'https://incubating.orkg.org/api/lists/R123' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 202

{
  "id" : "R123",
  "label" : "Default Label",
  "elements" : [ ],
  "created_at" : "2023-06-01T15:19:04.778631092+02:00",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "_class" : "list"
}

Response fields

Path Type Description

id

String

The identifier of the list.

label

String

The label of the list.

elements

Array

The ids of the elements of the list.

created_at

OffsetDateTime

The timestamp when the list was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this list.

_class

String

The type of object this json contains. Always has the value "list".

Fetching list elements

A GET request returns a paged list of elements, in order, with their full representations (see resources, classes, predicates, literals), that are part of the list. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/lists/R123/elements' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Updating lists

A PATCH request updates a list with all the given parameters. The response will be 204 No Content when successful.

Request fields

Path Type Description

label

String

The new label of the list. (optional)

elements

Array

The new ids of the elements of the list. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/lists/List1' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "List label",
  "elements" : [ "R1" ]
}'

Papers

Papers represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a paper representation.

The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.

Fetching a paper

A GET request provides information about a paper.

Curl request

$ curl 'https://incubating.orkg.org/api/papers/R8186' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.paper.v2+json'

Response fields

Path Type Description

id

String

The identifier of the paper.

title

String

The title of the paper.

research_fields

Array

The list of research fields the paper is assigned to.

research_fields[].id

String

The id of the research field.

research_fields[].label

String

The label of the research field.

identifiers

Object

The unique identifiers of the paper.

identifiers.doi

String

The DOI of the paper. (optional)

publication_info

Object

The publication info of the paper.

publication_info.published_month

Number

The month in which the paper was published. (optional)

publication_info.published_year

Number

The year in which the paper was published. (optional)

publication_info.published_in

String

The venue where the paper was published. (optional)

publication_info.url

String

The URL to the original paper. (optional)

authors

Array

The list of authors that originally contributed to the paper.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Object

The unique identifiers of the author.

authors[].identifiers.orcid

String

The ORCID of the author. (optional)

authors[].identifiers.google_scholar

String

The Google Scholar ID of the author. (optional)

authors[].identifiers.research_gate

String

The ResearchGate ID of the author. (optional)

authors[].identifiers.linked_in

String

The LinkedIn ID of the author. (optional)

authors[].identifiers.wikidata

String

The Wikidata ID of the author. (optional)

authors[].identifiers.web_of_science

String

The Web of Science id of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

contributions

Array

The list of contributions of the paper.

contributions[].id

String

The ID of the contribution.

contributions[].label

String

The label of the contribution.

organizations[]

Array

The list of IDs of the organizations the paper belongs to.

observatories[]

Array

The list of IDs of the observatories the paper belongs to.

extraction_method

String

The method used to extract the paper resource. Can be one of "unknown", "manual" or "automatic".

created_at

OffsetDateTime

The timestamp when the paper resource was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this paper.

verified

Boolean

Determines if the paper was verified by a curator.

visibility

String

Visibility of the paper. Can be one of "default", "featured", "unlisted" or "deleted".

Listing papers

A GET request returns a paged list of papers. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/papers' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.paper.v2+json'

The following list of request parameters are supported:

Only one request parameter can be used at a time.

Request parameters

Parameter Description

research_field

Optional filter for research field id.

title

Optional filter for the title of the paper. Uses exact matching.

visibility

Optional filter for visibility. Either of "listed", "featured", "unlisted" or "deleted".

created_by

Optional filter for research field id.

Fetching contributors for a paper

A GET request returns a paged list of contributors ids.

Curl request

$ curl 'https://incubating.orkg.org/api/papers/R8186/contributors' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Creating papers

A POST request creates a new paper with all the given parameters. The response will be 201 Created when successful. The paper (object) can be retrieved by following the URI in the Location header field.

Request fields

Snippet request-fields not found for operation::papers-create

Curl request

Snippet curl-request not found for operation::papers-create

HTTP response

Snippet http-response not found for operation::papers-create

Publishing papers

A POST request publishes an existing paper with the given parameters. It assigns a DOI to the paper and adds additional publication information, such as month and year published. The response will be 204 No Content when successful.

Request fields

Path Type Description

subject

String

The subject of the paper.

description

String

The description of the paper.

Curl request

$ curl 'https://incubating.orkg.org/api/papers/R123/publish' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "subject" : "paper subject",
  "description" : "paper description"
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/papers/R123

Contributions

Contributions represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts and provide a unified contribution representation.

The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.

Fetching a contribution

A GET request provides information about a contribution.

Curl request

$ curl 'https://incubating.orkg.org/api/contributions/R8199' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.contribution.v2+json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.contribution.v2+json
Content-Length: 157

{
  "id" : "R8199",
  "label" : "ORKG System",
  "classes" : [ "C123" ],
  "properties" : {
    "R456" : [ "R789", "R147" ]
  },
  "visibility" : "DEFAULT"
}

Response fields

Path Type Description

id

String

The identifier of the contribution.

label

String

The label of the contribution.

classes

Array

The classes of the contribution resource.

properties

Object

A map of predicate ids to lists of thing ids, that represent the statements that this contribution consists of.

visibility

String

Visibility of the contribution. Can be one of "default", "featured", "unlisted" or "deleted".

Listing contributions

A GET request returns a paged list of contributions. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/contributions' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.contribution.v2+json'

Creating contributions

A POST request creates a new contribution with all the given parameters. The response will be 201 Created when successful. The contribution (object) can be retrieved by following the URI in the Location header field.

Request fields

Path Type Description

resources

Object

Definition of resources that need to be created.

resources.*.label

String

The label of the resource.

resources.*.classes

Array

The list of classes of the resource.

literals

Object

Definition of literals that need to be created.

literals.*.label

String

The value of the literal.

literals.*.data_type

String

The data type of the literal.

predicates

Object

Definition of predicates that need to be created.

predicates.*.label

String

The label of the predicate.

predicates.*.description

String

The description of the predicate.

lists

Object

Definition of lists that need to be created.

lists.*.label

String

The label of the list.

lists.*.elements

Array

The IDs of the elements of the list.

contribution

Object

List of definitions of contribution that need to be created.

contribution.label

String

Label of the contribution.

contribution.classes

Array

The classes of the contribution resource.

contribution.statements

Object

Recursive map of statements contained within the contribution.

contribution.statements.*[].id

String

The ID of the object of the statement.

Curl request

$ curl 'https://incubating.orkg.org/api/papers/R3541/contributions' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.contribution.v2+json' \
    -d '{
  "resources" : {
    "#temp1" : {
      "label" : "MOTO",
      "classes" : [ "Result" ]
    }
  },
  "literals" : {
    "#temp2" : {
      "label" : "0.1",
      "data_type" : "xsd:decimal"
    }
  },
  "predicates" : {
    "#temp3" : {
      "label" : "hasResult",
      "description" : "has result"
    }
  },
  "lists" : {
    "#temp4" : {
      "label" : "list",
      "elements" : [ "#temp1", "C123" ]
    }
  },
  "contribution" : {
    "label" : "Contribution 1",
    "classes" : [ "C123" ],
    "statements" : {
      "P32" : [ {
        "id" : "R3003",
        "statements" : null
      } ],
      "HAS_EVALUATION" : [ {
        "id" : "#temp1",
        "statements" : null
      }, {
        "id" : "R3004",
        "statements" : {
          "#temp3" : [ {
            "id" : "R3003",
            "statements" : null
          }, {
            "id" : "#temp2",
            "statements" : null
          }, {
            "id" : "#temp4",
            "statements" : null
          } ],
          "P32" : [ {
            "id" : "#temp2",
            "statements" : null
          } ]
        }
      } ]
    }
  }
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/contributions/R123

Comparisons

Comparisons represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a comparison representation.

The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.

Fetching a comparison

A GET request provides information about a comparison.

Curl request

$ curl 'https://incubating.orkg.org/api/comparisons/R8186' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'

Response fields

Path Type Description

id

String

The identifier of the comparison.

title

String

The title of the comparison.

description

String

The description of the comparison.

research_fields

Array

The list of research fields the comparison is assigned to.

research_fields[].id

String

The id of the research field.

research_fields[].label

String

The label of the research field.

identifiers

Object

The unique identifiers of the comparison.

identifiers.doi

String

The DOI of the comparison. (optional)

publication_info

Object

The publication info of the comparison.

publication_info.published_month

Number

The month in which the comparison was published. (optional)

publication_info.published_year

Number

The year in which the comparison was published. (optional)

publication_info.published_in

String

The venue where the comparison was published. (optional)

publication_info.url

String

The URL to the original comparison. (optional)

authors

Array

The list of authors that originally contributed to the comparison.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Object

The unique identifiers of the author.

authors[].identifiers.orcid

String

The ORCID of the author. (optional)

authors[].identifiers.google_scholar

String

The Google Scholar ID of the author. (optional)

authors[].identifiers.research_gate

String

The ResearchGate ID of the author. (optional)

authors[].identifiers.linked_in

String

The LinkedIn ID of the author. (optional)

authors[].identifiers.wikidata

String

The Wikidata ID of the author. (optional)

authors[].identifiers.web_of_science

String

The Web of Science id of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

contributions

Array

The list of contributions of the comparison.

contributions[].id

String

The ID of the contribution.

contributions[].label

String

The label of the contribution.

visualizations

Array

The list of visualizations of the comparison.

visualizations[].id

String

The ID of the visualization.

visualizations[].label

String

The label of the visualization.

related_figures

Array

The list of related figures of the comparison.

related_figures[].id

String

The ID of the related figure.

related_figures[].label

String

The label of the related figure.

related_resources

Array

The list of related resources of the comparison.

related_resources[].id

String

The ID of the related resource.

related_resources[].label

String

The label of the related resource.

references[]

Array

The list of references of the comparison.

organizations[]

Array

The list of IDs of the organizations the comparison belongs to.

observatories[]

Array

The list of IDs of the observatories the comparison belongs to.

extraction_method

String

The method used to extract the comparison resource. Can be one of "unknown", "manual" or "automatic".

created_at

OffsetDateTime

The timestamp when the comparison resource was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this comparison.

previous_version

String

The ID of the resource of a previous version of the comparison.

is_anonymized

Boolean

Whether or not the comparison is anonymized.

visibility

String

Visibility of the comparison. Can be one of "default", "featured", "unlisted" or "deleted".

Listing comparisons

A GET request returns a paged list of comparisons. If no paging request parameters are provided, the default values will be used.

Fetching comparisons by DOI, title or contributor does also return previous versions of comparisons.

Curl request

$ curl 'https://incubating.orkg.org/api/comparisons' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'

The following list of request parameters are supported:

Only one request parameter can be used at a time.

Request parameters

Parameter Description

research_field

Optional filter for research field id.

title

Optional filter for the title of the comparison. Uses exact matching.

visibility

Optional filter for visibility. Either of "listed", "featured", "unlisted" or "deleted".

created_by

Optional filter for research field id.

A GET request provides information about a comparison related resource.

$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-resources/R1563' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'
Path Type Description

id

String

The identifier of the comparison related resource.

label

String

The title of label comparison related resource.

image

String

The url for the image of the comparison related resource.

url

String

The url of the comparison related resource.

description

String

The description of the comparison related resource.

A GET request returns a paged list of comparison related resources.

$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-resources/R1563' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'

A GET request provides information about a comparison related figure.

$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-figures/R5476' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'
Path Type Description

id

String

The identifier of the comparison related figure.

label

String

The title of label comparison related figure.

image

String

The url for the image of the comparison related figure.

description

String

The description of the comparison related figure.

A GET request returns a paged list of comparison related figures.

$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-figures/R5476' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json'

Publishing comparisons

A POST request publishes an existing comparison with the given parameters. It assigns a DOI to the comparison and adds additional publication information, such as month and year published. The response will be 204 No Content when successful.

Request fields

Path Type Description

subject

String

The subject of the comparison.

description

String

The description of the comparison.

Curl request

$ curl 'https://incubating.orkg.org/api/comparisons/R123/publish' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "subject" : "comparison subject",
  "description" : "comparison description"
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/comparisons/R123

Visualizations

Visualizations represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a visualization representation.

The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.

Fetching a visualization

A GET request provides information about a visualization.

Curl request

$ curl 'https://incubating.orkg.org/api/visualizations/R8186' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.visualization.v2+json'

Response fields

Path Type Description

id

String

The identifier of the visualization.

title

String

The title of the visualization.

description

String

The description of the visualization.

authors

Array

The list of authors that originally contributed to the visualization.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Object

The unique identifiers of the author.

authors[].identifiers.orcid

String

The ORCID of the author. (optional)

authors[].identifiers.google_scholar

String

The Google Scholar ID of the author. (optional)

authors[].identifiers.research_gate

String

The ResearchGate ID of the author. (optional)

authors[].identifiers.linked_in

String

The LinkedIn ID of the author. (optional)

authors[].identifiers.wikidata

String

The Wikidata ID of the author. (optional)

authors[].identifiers.web_of_science

String

The Web of Science id of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

organizations[]

Array

The list of IDs of the organizations the visualization belongs to.

observatories[]

Array

The list of IDs of the observatories the visualization belongs to.

extraction_method

String

The method used to extract the visualization resource. Can be one of "unknown", "manual" or "automatic".

created_at

OffsetDateTime

The timestamp when the visualization resource was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this visualization.

visibility

String

Visibility of the visualization. Can be one of "default", "featured", "unlisted" or "deleted".

Listing visualizations

A GET request returns a paged list of visualizations. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/visualizations' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.visualization.v2+json'

The following list of request parameters are supported:

Only one request parameter can be used at a time.

Request parameters

Parameter Description

title

Optional filter for the title of the visualization. Uses exact matching.

visibility

Optional filter for visibility. Either of "listed", "featured", "unlisted" or "deleted".

created_by

Optional filter for research field id.

RDF Integration

RDF Dump

The ORKG provides a dump of the entire graph in RDF, the dump is in N-Triples format.

Getting dump

This endpoint is deprecated. Clients are advised to update, because this endpoint will be removed in the future.

Dumps cannot be created on-the-fly anymore, but can be downloaded from /files/rdf-dumps. The response will be 301 Moved Permanently, pointing to the latest version of the dump.

Curl request
$ curl 'https://incubating.orkg.org/api/rdf/dump' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/n-triples'
HTTP response
HTTP/1.1 301 Moved Permanently
Location: https://incubating.orkg.org/files/rdf-dumps/rdf-export-orkg.nt

Resolvable Vocabulary

ORKG entities in RDF format are resolvable. Each URI refers to the description of the corresponding entity in some RDF serialization.

Resolve a resource

A GET request to get the description of an ORKG resource.

a HTTP Accept header should be provided with one of the values from the table below. Otherwise, the request will be redirected to the frontend UI to see the HTML description page.
Curl request
$ curl 'http://localhost:8080/api/vocab/resource/R5' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 195

[ {
  "@id" : "http://orkg.org/orkg/resource/R5",
  "@type" : [ "http://orkg.org/orkg/class/Resource" ],
  "http://www.w3.org/2000/01/rdf-schema#label" : [ {
    "@value" : "Resource 1"
  } ]
} ]

Resolve a predicate

A GET request to get the description of an ORKG predicate.

a HTTP Accept header should be provided with one of the values from the table below. Otherwise, the request will be redirected to the frontend UI to see the HTML description page.
Curl request
$ curl 'http://localhost:8080/api/vocab/predicate/P2' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 198

[ {
  "@id" : "http://orkg.org/orkg/predicate/P2",
  "@type" : [ "http://orkg.org/orkg/class/Predicate" ],
  "http://www.w3.org/2000/01/rdf-schema#label" : [ {
    "@value" : "Predicate 1"
  } ]
} ]

Resolve a class

A GET request to get the description of an ORKG class.

a HTTP Accept header should be provided with one of the values from the table below. Otherwise, the request will be redirected to the frontend UI to see the HTML description page.
Curl request
$ curl 'http://localhost:8080/api/vocab/class/C1' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 189

[ {
  "@id" : "http://orkg.org/orkg/class/C1",
  "@type" : [ "http://www.w3.org/2002/07/owl#Class" ],
  "http://www.w3.org/2000/01/rdf-schema#label" : [ {
    "@value" : "Class 1"
  } ]
} ]

Allowed accept headers

This collection of HTTP Accept headers are allowed by the system and the corresponding serialization format.

Table 1. HTTP RDF serialization accept headers
Header Format

application/n-triples

N-Triples

application/rdf+xml

RDF XML

text/n3

N3

application/json

JSON-LD

application/trig

TriG

application/x-trig

TriG

application/n-quads

N-Quads

text/x-nquads

N-Quads

text/nquads

N-Quads

application/turtle

Turtle

text/turtle

Turtle

RDF Hints

Resource information can be obtained from the /api/rdf/hints endpoint. It supports the following request parameters:

Parameter Description

q

The search string for the label.

exact

Determine if exact search should be performed. (Default: false)

type

The type of entity to be retrieved. Can be one of property, class, or item.
The type parameter differs from the conventions used in this document. property refers to predicates, item to resources.

Contributors

Contributors are people contributing to the ORKG. They can become a member of an organization or join an observatory.

Obtaining contributor information

Information about a specific contributor can be obtained by sending a GET request to the contributor endpoint:

Curl request

$ curl 'http://localhost:8080/api/contributors/223e7231-d356-4c68-ad9d-e3c087821ba8' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 392

{
  "id" : "223e7231-d356-4c68-ad9d-e3c087821ba8",
  "display_name" : "Some User",
  "joined_at" : "2023-09-25T15:44:39.073487Z",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "gravatar_id" : "9ab3be8f21fe883eeb99423a16618a34",
  "avatar_url" : "https://www.gravatar.com/avatar/9ab3be8f21fe883eeb99423a16618a34"
}

The response contains the following fields:

Response fields

Path Type Description

id

String

The contributor ID.

display_name

String

The name of the contributor.

joined_at

String

The time the contributor joined the project (in ISO 8601 format).

organization_id

String

The ID of the organization the contributor belongs to. All zeros if the contributor is not part of an organization.

observatory_id

String

The ID of the observatory the contributor belongs to. All zeros if the contributor has not joined an observatory.

gravatar_id

String

The ID of the contributor on Gravatar. (Useful for generating profile pictures.)

avatar_url

String

A URL to an avatar representing the user. Currently links to Gravatar.

Organizations

Organizations represent institutes or groups. These can handle further smaller groups named Observatories.

Listing Organizations

A GET request lists all organizations:

Curl request

$ curl 'http://localhost:8080/api/organizations/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 273

[ {
  "id" : "3f2c60a1-841a-4160-9517-feeccafb6390",
  "name" : "Test Organization",
  "created_by" : "d186bd0a-4339-4c9a-b286-b9dc7fac08c0",
  "homepage" : "https://www.example.org",
  "observatory_ids" : [ ],
  "display_id" : "test_organization",
  "type" : "GENERAL"
} ]

Fetching an organization

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/organizations/269044e6-d36a-4273-93c4-204ec6413b12' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 269

{
  "id" : "269044e6-d36a-4273-93c4-204ec6413b12",
  "name" : "Test Organization",
  "created_by" : "259e2af7-24e8-4e3f-9448-1bd534aea2c2",
  "homepage" : "https://www.example.org",
  "observatory_ids" : [ ],
  "display_id" : "test_organization",
  "type" : "GENERAL"
}

Observatories

Observatories are groups of experts affiliated with different institutions that curates and organize ORKG content for a specific discipline. Observatories represent groups which are managed by Organizations. One Observatory can be managed by many organizations.

Listing Observatories

A GET request lists all organizations:

Curl request

$ curl 'http://localhost:8080/api/observatories/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 810

{
  "content" : [ {
    "id" : "260e7c47-f6ee-490c-88e4-02648784a381",
    "name" : "Test Observatory",
    "description" : "Example description",
    "members" : [ ],
    "research_field" : {
      "id" : "R5",
      "label" : "label"
    },
    "organization_ids" : [ "e7fdf9a7-6e12-461a-964f-1e3aeefa0587" ],
    "display_id" : "test_observatory"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 1,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "size" : 20,
  "empty" : false
}

Fetching an observatory

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/observatories/12f57de6-e3dd-4370-8a9e-2e42b0a5061e' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 313

{
  "id" : "12f57de6-e3dd-4370-8a9e-2e42b0a5061e",
  "name" : "Test Observatory",
  "description" : "Example description",
  "members" : [ ],
  "research_field" : {
    "id" : "R4",
    "label" : "label"
  },
  "organization_ids" : [ "76513e39-7e2d-42c5-b9de-7dcca979941a" ],
  "display_id" : "test_observatory"
}

Research Problems

Research problems in the ORKG are important concepts and thus have their own API enpoint to get all related concepts.

Fields per problem

A GET request get all research fields relating to a problem

Users per problem

A GET request to get a paginated list of ORKG users that contributed to contributions where a problem is being addressed.

Curl request

$ curl 'http://localhost:8080/api/problems/R219/users?size=4' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 449

[ {
  "user" : {
    "id" : "d1830f67-e517-40a6-b98e-81c3db1c2aee",
    "display_name" : "test_user",
    "joined_at" : "2023-09-25T15:44:59.51844Z",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "gravatar_id" : "909c3113e76a1d52913c88135fbb431e",
    "avatar_url" : "https://www.gravatar.com/avatar/909c3113e76a1d52913c88135fbb431e"
  },
  "contributions" : 1
} ]

Response fields

Path Type Description

[]

Array

A list of users

[].user

Object

The user object

[].user.id

String

The UUID of the user in the system

[].user.gravatar_id

String

The gravatar id of the user

[].user.display_name

String

The user’s display name

[].user.avatar_url

String

The user’s avatar url (gravatar url)

[].user.joined_at

String

the datetime when the user was created

[].user.organization_id

String

the organization id that this user belongs to

[].user.observatory_id

String

the observatory id that this user belongs to

[].contributions

Number

The number of contributions this user created

Authors per problem

A GET request provides a paginated list of authors that have papers addressing a certain research problem

Research Fields

Research fields are meta objects that help better classify the content within the ORKG. The research field is essentially a resource and hence inherits all the specifications of resource.

Listing Problems in field

A GET request lists all problems used within all papers under the specified research field:

Curl request

$ curl 'http://localhost:8080/api/research-fields/R221/problems/' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1046

{
  "content" : [ {
    "problem" : {
      "id" : "R224",
      "label" : "Problem 1",
      "classes" : [ "Problem" ],
      "shared" : 1,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T15:45:00.272898Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "papers" : 1
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 1,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "size" : 20,
  "empty" : false
}

Listing Papers in field

A GET request lists all papers under the specified research field.

Listing Contributors in field

A GET request lists all contributors under the specified research field.

Listing Comparisons in field

A GET request lists all comparisons under the specified research field.

Listing Problems in field including sub research fields

A GET request lists all problems used within all papers under the specified research field and sub research fields.

Listing Papers in field including sub research fields

A GET request lists all papers under the specified research field and sub research fields.

Listing Contributors in field including sub research fields

A GET request lists all contributors under the entire tree of the specified research field, comparisons, papers and individual contributions.

Listing Comparisons in field including sub research fields

A GET request lists all comparisons under the specified research field and sub research fields.

Listing subfields

A GET request lists all sub research fields of a research field.

Curl request

$ curl 'https://incubating.orkg.org/api/research-fields/R123/children' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 874

{
  "content" : [ {
    "resource" : {
      "id" : "subfield",
      "label" : "Default Label",
      "classes" : [ "ResearchField" ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:58.92771Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "child_count" : 1
  } ],
  "pageable" : "INSTANCE",
  "totalElements" : 1,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 1,
  "first" : true,
  "size" : 1,
  "empty" : false
}
Path Type Description

child_count

Number

The count of direct subfields that this research field has.

resource

Object

Resource representation of the research field resource.

Listing parent research fields

A GET request lists all parent research fields of a research field.

Curl request

$ curl 'https://incubating.orkg.org/api/research-fields/R123/parents' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 797

{
  "content" : [ {
    "id" : "parent",
    "label" : "Default Label",
    "classes" : [ "ResearchField" ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T08:38:58.812431Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : "INSTANCE",
  "totalElements" : 1,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 1,
  "first" : true,
  "size" : 1,
  "empty" : false
}

Listing root research fields of a subfield

A GET request lists all root research fields of the specified research field.

Curl request

$ curl 'https://incubating.orkg.org/api/research-fields/subfield/roots' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 795

{
  "content" : [ {
    "id" : "root",
    "label" : "Default Label",
    "classes" : [ "ResearchField" ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T08:38:58.845359Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : "INSTANCE",
  "totalElements" : 1,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 1,
  "first" : true,
  "size" : 1,
  "empty" : false
}

Listing all root research fields

A GET requests lists all root research fields.

Curl request

$ curl 'https://incubating.orkg.org/api/research-fields/roots' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 794

{
  "content" : [ {
    "id" : "root",
    "label" : "Default Label",
    "classes" : [ "ResearchField" ],
    "shared" : 0,
    "featured" : false,
    "unlisted" : false,
    "verified" : false,
    "extraction_method" : "UNKNOWN",
    "_class" : "resource",
    "created_at" : "2023-09-25T08:38:58.96744Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "formatted_label" : null
  } ],
  "pageable" : "INSTANCE",
  "totalElements" : 1,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 1,
  "first" : true,
  "size" : 1,
  "empty" : false
}

Listing research field hierarchy

A GET request lists all paths from root research fields to the specified research field.

Curl request

$ curl 'https://incubating.orkg.org/api/research-fields/subfield/hierarchy' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 885

{
  "content" : [ {
    "resource" : {
      "id" : "subfield",
      "label" : "Default Label",
      "classes" : [ "ResearchField" ],
      "shared" : 0,
      "featured" : false,
      "unlisted" : false,
      "verified" : false,
      "extraction_method" : "UNKNOWN",
      "_class" : "resource",
      "created_at" : "2023-09-25T08:38:58.649322Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "formatted_label" : null
    },
    "parent_ids" : [ "parent" ]
  } ],
  "pageable" : "INSTANCE",
  "totalElements" : 1,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "number" : 0,
  "numberOfElements" : 1,
  "first" : true,
  "size" : 1,
  "empty" : false
}
Path Type Description

parent_ids

Array

The ids of the parent research fields.

resource

Object

Resource representation of the research field resource.

Listing statistics about a research field

A GET request lists statistics about a research field. Optionally accounts for subfields.

Curl request

$ curl 'https://incubating.orkg.org/api/stats/research-fields/R1?includeSubfields=false' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 71

{
  "id" : "R1",
  "papers" : 25,
  "comparisons" : 5,
  "total" : 30
}

Datasets & Benchmarks

Some datasets and benchmarks on said datasets are imported into the ORKG. Certain statistics can be obtained through the benchmark endpoint of the rest API.

Listing research fields with benchmarks

A GET request lists all the research fields with benchmarks (i.e., all research fields that have papers containing benchmarks in their contributions).

Curl request

$ curl 'http://localhost:8080/api/research-fields/benchmarks' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 522

{
  "content" : [ {
    "id" : "R80",
    "label" : "Field 1"
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 1,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "size" : 20,
  "empty" : false
}

Listing Benchmarks by Field

A GET request lists benchmarks under a certain research field.

Curl request

$ curl 'http://localhost:8080/api/benchmarks/summary/research-field/R98' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 989

{
  "content" : [ {
    "research_problem" : {
      "id" : "R104",
      "label" : "Problem 1"
    },
    "research_fields" : [ {
      "id" : "R98",
      "label" : "Field with a dataset"
    } ],
    "total_papers" : 1,
    "total_datasets" : 2,
    "total_codes" : 5
  }, {
    "research_problem" : {
      "id" : "R105",
      "label" : "Problem 2"
    },
    "research_fields" : [ {
      "id" : "R98",
      "label" : "Field with a dataset"
    } ],
    "total_papers" : 1,
    "total_datasets" : 2,
    "total_codes" : 5
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Benchmark Summary

A GET request lists the datasets for a research problem (a.k.a. Benchmark Summary)

Curl request

$ curl 'http://localhost:8080/api/datasets/research-problem/R67' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 717

{
  "content" : [ {
    "id" : "R78",
    "label" : "Dataset 1",
    "total_models" : 4,
    "total_papers" : 1,
    "total_codes" : 0
  }, {
    "id" : "R79",
    "label" : "Dataset 2",
    "total_models" : 0,
    "total_papers" : 1,
    "total_codes" : 3
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Benchmark Unpacked

A GET request lists summary for a dataset (a.k.a. Benchmark unpacked).

Curl request

$ curl 'http://localhost:8080/api/datasets/R49/problem/R50/summary' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1111

{
  "content" : [ {
    "model_name" : "Model 1",
    "model_id" : "R57",
    "score" : "2.55",
    "metric" : "Metric 1",
    "paper_id" : "R52",
    "paper_title" : "paper",
    "paper_month" : null,
    "paper_year" : null,
    "code_urls" : [ "https://some-code-3.cool", "https://some-code-1.cool", "https://some-code-2.cool" ]
  }, {
    "model_name" : "Model 1",
    "model_id" : "R57",
    "score" : "4548",
    "metric" : "Metric 2",
    "paper_id" : "R52",
    "paper_title" : "paper",
    "paper_month" : null,
    "paper_year" : null,
    "code_urls" : [ "https://some-code-3.cool", "https://some-code-1.cool", "https://some-code-2.cool" ]
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : false,
      "unsorted" : true,
      "empty" : true
    },
    "pageNumber" : 0,
    "pageSize" : 20,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "last" : true,
  "totalElements" : 2,
  "totalPages" : 1,
  "sort" : {
    "sorted" : false,
    "unsorted" : true,
    "empty" : true
  },
  "first" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "size" : 20,
  "empty" : false
}

Reproducibility Score

The reproducibility score measures the availability, accessibility, linkability, and license of a resource.

License

License information of external code repositories can be obtained through the orkg to compute a reproducibility score for a resource.

The endpoint currently only supports GitHub repository URIs.

Curl request

$ curl 'https://incubating.orkg.org/api/licenses?uri=https://github.com/github/docs' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.license.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.license.v1+json'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.license.v1+json
Content-Length: 29

{
  "license" : "CC-BY-4.0"
}

ORKG Widget

This API is intended for internal use of the ORKG widget, and not meant to be consumed by clients. It is documented here for completeness. Client authors can ignore it.

The widget can obtain information via a GET request to /api/widgets/ by providing one of the request parameters. All request parameters are mutually exclusive. Providing none or more than one will respond with status code 400 (Bad Request).

Curl request

$ curl 'https://incubating.orkg.org/api/widgets/?doi=10.1000/182' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Request parameters

Parameter Description

doi

The DOI of the resource to search.

title

The title of the resource to search.

Response fields

Path Type Description

id

String

The identifier of the resource.

doi

String

The DOI of the resource. May be null if the resource does not have a DOI.

title

String

The title of the resource.

class

String

The class of the resource. Always one of Comparison, Paper, SmartReviewPublished.

num_statements

Number

The number of statements connected to the resource if the class is Paper, or 0 in all other cases.

Sorting and Pagination

For all request that lists entities, pagination and sorting are applied automatically. The attributes of paged responses are described in the section about Page representations.

Endpoints supporting paging all take the following (optional) request parameters:

Parameter Description

page

The page number requested, 0-indexed.

size

The number of elements per page. May be lowered if it exceeds the limit.

sort

A string in the form "{property},{direction}". Sortable properties are dependent on the endpoint. Direction can be "asc" or "desc". Parameter can be repeated multiple times. The sorting is order-dependent.

An example of a response of a paged list looks like this:

{
  "content" : [ "bar", "baz", "foo" ],
  "pageable" : {
    "sort" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 10,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 3,
  "totalPages" : 1,
  "last" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 3,
  "first" : true,
  "size" : 10,
  "empty" : false
}
The elements in content can be objects of arbitrary structure and are sorted according to the request parameters, if the endpoint supports it.

By default, sorting is done by the created_at property (time-based).

Table 2. Sorting keys allowed by the API
Key Description

For sorting resources & predicates

id

the id of the resource or predicate

label

the label of the resource or the predicate

created

the datetime timestamp of the creation

For sorting statements

id

the statement id

created

the datetime timestamp of the creation

sub.label

the label of the subject

sub.created

the creation timestamp of the subject

rel.label

the label of the predicate

rel.created

the creation timestamp of the predicate

obj.label

the label of the object

obj.created

the creation timestamp of the object

Representations

This section contains the resource definitions (also called representations) of the entities of this API.

Basic Types

Timestamps

All timestamps used in this API are in ISO 8601 format. Although nanosecond precision is available currently, clients MUST NOT rely on it, as it might be subject to change.

Errors

Path Type Description

status

Number

The HTTP status code of the error. This is equal to the status code of the request itself and MUST only be used for display purposes.

error

String

The human-readable error description of the status code, e.g. "Bad Request" for code 400.

message

String

A human-readable, and hopefully helpful message that explains the error.

path

String

The path to which the request was made that caused the error.

timestamp

String

The timestamp of when the error happened.

Pages

Path Type Description

content

Array

The result of the request as a (sorted) array.

empty

Boolean

Determines if the current page is empty.

first

Boolean

Determines if the current page is the first one.

last

Boolean

Determines if the current page is the last one.

number

Number

The number of the current page.

numberOfElements

Number

The number of elements currently on this page.

size

Number

The size of the current page.

sort

Object

The sorting parameters for this page.

sort.empty

Boolean

Determines if the sort object is empty.

sort.sorted

Boolean

Determines if the page is sorted. Inverse of unsorted.

sort.unsorted

Boolean

Determines if the page is unsorted. Inverse of sorted.

totalElements

Number

The total amounts of elements.

totalPages

Number

The number of total pages.

Entities

Literal

Path Type Description

id

String

The identifier of the literal.

label

String

The literal value.

datatype

String

The datatype of the literal. Can be a (prefixed) URI.

created_at

OffsetDateTime

The timestamp when the literal was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this literal.

_class

String

An indicator which type of entity was returned. Always has the value “literal”.