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.

Content Negotiation

Some endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request. Furthermore, some media types support defining additional parameters to enable specific response representation features.

The following list of media type parameters are supported:

Table 1. Media type parameters supported by the API
Parameter Name Acceptable Values Supported Media Types Description

formatted-labels

V1

application/json

When specified, enables serialization of the formatted_label field for resource representations.

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 'https://incubating.orkg.org/api/statements' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

The following list of request parameters are supported:

Request parameters

Parameter Description

subject_classes

A comma-separated set of classes that the subject of the statement must have. The ids Resource, Class and Predicate can be used to filter for a general type of subject. (optional)

subject_id

Filter for the subject id. (optional)

subject_label

Filter for the label of the subject. The label has to match exactly. (optional)

predicate_id

Filter for the predicate id of the statement. (optional)

created_by

Filter for the UUID of the user or service who created this statement. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned statement can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned statement can have. (optional)

object_classes

A comma-separated set of classes that the object of the statement must have. The ids Resource, Class, Predicate and Literal can be used to filter for a general type of object. (optional)

object_id

Filter for the object id. (optional)

object_label

Filter for the label of the object. The label has to match exactly. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/statements?subject_classes=Contribution%2CC123&subject_id=R1&subject_label=Default+Label&predicate_id=P1&created_by=34da5516-7901-4b0d-94c5-b062082e11a7&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&object_classes=Literal&object_id=L1&object_label=Default+Label' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'
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" : "R400",
  "predicate_id" : "P16",
  "object_id" : "R401"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/statements/
Content-Type: application/json
Content-Length: 1466

{
  "created_at" : "2024-07-19T14:01:10.596870996Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "id" : "S1172",
  "modifiable" : true,
  "object" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-07-19T14:01:10.562594313Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R401",
    "label" : "two",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 1,
    "unlisted" : false,
    "verified" : false
  },
  "predicate" : {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:01:10.567017302Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P16",
    "label" : "less than",
    "modifiable" : true
  },
  "subject" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-07-19T14:01:10.558233884Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R400",
    "label" : "one",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 0,
    "unlisted" : false,
    "verified" : false
  }
}

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/S1176' -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: 1460

{
  "created_at" : "2024-07-19T14:01:10.992465489Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "id" : "S1176",
  "modifiable" : true,
  "object" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-07-19T14:01:10.854673199Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R407",
    "label" : "two",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 1,
    "unlisted" : false,
    "verified" : false
  },
  "predicate" : {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:01:10.980508931Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P19",
    "label" : "blah",
    "modifiable" : true
  },
  "subject" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-07-19T14:01:10.84897359Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R406",
    "label" : "one",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 0,
    "unlisted" : false,
    "verified" : false
  }
}

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/R402/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: 4722

{
  "root" : "R402",
  "statements" : [ {
    "created_at" : "2024-07-19T14:01:10.770264557Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S1175",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.746269352Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R405",
      "label" : "four",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 1,
      "unlisted" : false,
      "verified" : false
    },
    "predicate" : {
      "_class" : "predicate",
      "created_at" : "2024-07-19T14:01:10.749823882Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P17",
      "label" : "blah",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.739979314Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R403",
      "label" : "two",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 1,
      "unlisted" : false,
      "verified" : false
    }
  }, {
    "created_at" : "2024-07-19T14:01:10.766107198Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S1174",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.743130523Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R404",
      "label" : "three",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 1,
      "unlisted" : false,
      "verified" : false
    },
    "predicate" : {
      "_class" : "predicate",
      "created_at" : "2024-07-19T14:01:10.752764011Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P18",
      "label" : "blub",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.736252295Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R402",
      "label" : "one",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  }, {
    "created_at" : "2024-07-19T14:01:10.760711169Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S1173",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.739979314Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R403",
      "label" : "two",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 1,
      "unlisted" : false,
      "verified" : false
    },
    "predicate" : {
      "_class" : "predicate",
      "created_at" : "2024-07-19T14:01:10.749823882Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P17",
      "label" : "blah",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-07-19T14:01:10.736252295Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R402",
      "label" : "one",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  } ]
}

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: 4510

[ {
  "id" : "R1",
  "statements" : {
    "content" : [ {
      "created_at" : "2023-10-02T15:32:18.753961+01:00",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
      "id" : "S1",
      "modifiable" : true,
      "object" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R2",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      },
      "predicate" : {
        "_class" : "predicate",
        "created_at" : "2023-10-04T13:30:16.931457+01:00",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
        "description" : null,
        "id" : "P1",
        "label" : "some predicate label",
        "modifiable" : true
      },
      "subject" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R1",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      }
    } ],
    "empty" : false,
    "first" : true,
    "last" : true,
    "number" : 0,
    "numberOfElements" : 1,
    "pageable" : {
      "offset" : 0,
      "pageNumber" : 0,
      "pageSize" : 5,
      "paged" : true,
      "sort" : {
        "empty" : true,
        "sorted" : false,
        "unsorted" : true
      },
      "unpaged" : false
    },
    "size" : 5,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "totalElements" : 1,
    "totalPages" : 1
  }
}, {
  "id" : "R3",
  "statements" : {
    "content" : [ {
      "created_at" : "2023-10-02T15:32:18.753961+01:00",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
      "id" : "S2",
      "modifiable" : true,
      "object" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R4",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      },
      "predicate" : {
        "_class" : "predicate",
        "created_at" : "2023-10-04T13:30:16.931457+01:00",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
        "description" : null,
        "id" : "P2",
        "label" : "some predicate label",
        "modifiable" : true
      },
      "subject" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R3",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      }
    } ],
    "empty" : false,
    "first" : true,
    "last" : true,
    "number" : 0,
    "numberOfElements" : 1,
    "pageable" : {
      "offset" : 0,
      "pageNumber" : 0,
      "pageSize" : 5,
      "paged" : true,
      "sort" : {
        "empty" : true,
        "sorted" : false,
        "unsorted" : true
      },
      "unpaged" : false
    },
    "size" : 5,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "totalElements" : 1,
    "totalPages" : 1
  }
} ]

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: 4510

[ {
  "id" : "R2",
  "statements" : {
    "content" : [ {
      "created_at" : "2023-10-02T15:32:18.753961+01:00",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
      "id" : "S1",
      "modifiable" : true,
      "object" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R2",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      },
      "predicate" : {
        "_class" : "predicate",
        "created_at" : "2023-10-04T13:30:16.931457+01:00",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
        "description" : null,
        "id" : "P1",
        "label" : "some predicate label",
        "modifiable" : true
      },
      "subject" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R1",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      }
    } ],
    "empty" : false,
    "first" : true,
    "last" : true,
    "number" : 0,
    "numberOfElements" : 1,
    "pageable" : {
      "offset" : 0,
      "pageNumber" : 0,
      "pageSize" : 5,
      "paged" : true,
      "sort" : {
        "empty" : true,
        "sorted" : false,
        "unsorted" : true
      },
      "unpaged" : false
    },
    "size" : 5,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "totalElements" : 1,
    "totalPages" : 1
  }
}, {
  "id" : "R4",
  "statements" : {
    "content" : [ {
      "created_at" : "2023-10-02T15:32:18.753961+01:00",
      "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
      "id" : "S2",
      "modifiable" : true,
      "object" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R4",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      },
      "predicate" : {
        "_class" : "predicate",
        "created_at" : "2023-10-04T13:30:16.931457+01:00",
        "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
        "description" : null,
        "id" : "P2",
        "label" : "some predicate label",
        "modifiable" : true
      },
      "subject" : {
        "_class" : "resource",
        "classes" : [ ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R3",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      }
    } ],
    "empty" : false,
    "first" : true,
    "last" : true,
    "number" : 0,
    "numberOfElements" : 1,
    "pageable" : {
      "offset" : 0,
      "pageNumber" : 0,
      "pageSize" : 5,
      "paged" : true,
      "sort" : {
        "empty" : true,
        "sorted" : false,
        "unsorted" : true
      },
      "unpaged" : false
    },
    "size" : 5,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "totalElements" : 1,
    "totalPages" : 1
  }
} ]

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: 3262

[ {
  "id" : "S1",
  "statement" : {
    "created_at" : "2023-10-02T15:32:18.753961+01:00",
    "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
    "id" : "S1",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R5",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    },
    "predicate" : {
      "_class" : "predicate",
      "created_at" : "2023-10-04T13:30:16.931457+01:00",
      "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
      "description" : null,
      "id" : "P3",
      "label" : "some predicate label",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R1",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  }
}, {
  "id" : "S2",
  "statement" : {
    "created_at" : "2023-10-02T15:32:18.753961+01:00",
    "created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
    "id" : "S2",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R5",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    },
    "predicate" : {
      "_class" : "predicate",
      "created_at" : "2023-10-04T13:30:16.931457+01:00",
      "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
      "description" : null,
      "id" : "P3",
      "label" : "some predicate label",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R3",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  }
} ]

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: 1006

{
  "content" : [ {
    "_class" : "class",
    "created_at" : "2024-07-19T14:00:58.688198203Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C5",
    "label" : "research contribution",
    "modifiable" : true,
    "uri" : null
  }, {
    "_class" : "class",
    "created_at" : "2024-07-19T14:00:58.691234473Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C6",
    "label" : "programming language",
    "modifiable" : true,
    "uri" : null
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

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

id

String

The class id (optional)

label

String

The class label

uri

String

The class URI

Curl request

$ curl 'https://incubating.orkg.org/api/classes/' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "id" : "C123",
  "label" : "foo",
  "uri" : "http://example.org/bar"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/classes/C123
Content-Type: application/json
Content-Length: 254

{
  "_class" : "class",
  "created_at" : "2023-10-05T12:29:15.3155145+01:00",
  "created_by" : "dc8b2055-c14a-4e9f-9fcd-e0b79cf1f834",
  "description" : null,
  "id" : "C123",
  "label" : "foo",
  "modifiable" : true,
  "uri" : "http://example.org/bar"
}

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.

modifiable

Boolean

Whether this class can be modified.

Fetching a class

A GET request provides information about a class.

Curl request

$ curl 'http://localhost:8080/api/classes/C4' -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: 247

{
  "_class" : "class",
  "created_at" : "2024-07-19T14:00:58.594905964Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "description" : null,
  "id" : "C4",
  "label" : "research contribution",
  "modifiable" : true,
  "uri" : null
}

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: 1000

{
  "content" : [ {
    "_class" : "class",
    "created_at" : "2024-07-19T14:00:57.968069092Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C3",
    "label" : "research topic",
    "modifiable" : true,
    "uri" : null
  }, {
    "_class" : "class",
    "created_at" : "2024-07-19T14:00:57.961906173Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C1",
    "label" : "research contribution",
    "modifiable" : true,
    "uri" : null
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

Editing a class

A PATCH request updates a class with a new given label and URI. Only fields provided in the response, and therefore non-null, will be updated. The response will be 200 OK when successful.

Request fields

Path Type Description

label

String

The updated class label (optional)

uri

String

The updated class label (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/classes/EXISTS' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "uri" : "https://example.org/some/new#URI",
  "label" : "some label"
}'

HTTP response

HTTP/1.1 200 OK

A PUT request updates a class with a new given label and URI. All fields will be updated in the process. The response will be 200 OK when successful. The updated class is returned in the body for convenience.

Request fields

Path Type Description

label

String

The updated class label

uri

String

The updated class label

Curl request

$ curl 'https://incubating.orkg.org/api/classes/EXISTS' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "new label",
  "uri" : "https://example.org/some/new#URI"
}'

HTTP response

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

{
  "_class" : "class",
  "created_at" : "2023-10-05T12:29:15.3155145+01:00",
  "created_by" : "dc8b2055-c14a-4e9f-9fcd-e0b79cf1f834",
  "description" : null,
  "id" : "EXISTS",
  "label" : "new label",
  "modifiable" : true,
  "uri" : "https://example.org/some/new#URI"
}

Importing a class

The Open Research Knowledge Graph REST API provides two endpoints for importing classes from external ontologies.

Importing a class by URI

A POST request imports a class from an external ontology by a given URI. The response will be 201 Created when successful, even when the class was already imported.

Curl request
$ curl 'https://incubating.orkg.org/api/import/classes' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "uri" : "https://www.wikidata.org/entity/Q42"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/classes/C123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

uri

String

The uri of the class to import.

Importing a class by short form

A POST request imports a class from an external ontology by a given short form id. The response will be 201 Created when successful, even when the class was already imported.

Curl request
$ curl 'https://incubating.orkg.org/api/import/classes' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "short_form" : "Q42"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/classes/C123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

short_form

String

The short form id of the resource to import.

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.

Curl request

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

The following list of request parameters are supported:

Request parameters

Parameter Description

q

A search term that must be contained in the label. (optional)

exact

Whether label matching is exact or fuzzy (optional, default: false)

visibility

Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional)

created_by

Filter for the UUID of the user or service who created this resource. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional)

include

A comma-separated set of classes that the resource must have. (optional)

exclude

A comma-separated set of classes that the resource must not have. (optional)

base_class

The id of the base class that the resource has to be an instance of. (optional)

observatory_id

Filter for the UUID of the observatory that the resource belongs to. (optional)

organization_id

Filter for the UUID of the organization that the resource belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/resources?q=label&exact=true&visibility=ALL_LISTED&created_by=b7c81eed-52e1-4f7a-93bf-e6d331b8df7b&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&include=Include1%2CInclude2&exclude=Exclude1%2CExclude2&base_class=BaseClass&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'
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.

classes

Array

The classes of the resource. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN")

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/R5
Content-Type: application/json
Content-Length: 479

{
  "_class" : "resource",
  "classes" : [ ],
  "created_at" : "2024-07-19T14:01:07.988571079Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "extraction_method" : "UNKNOWN",
  "featured" : false,
  "formatted_label" : null,
  "id" : "R5",
  "label" : "foo",
  "modifiable" : true,
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "shared" : 0,
  "unlisted" : false,
  "verified" : false
}

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. See Content Negotiation for information on how to obtain this value.

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.

Request fields

Path Type Description

label

String

The updated resource label. (optional)

classes

Array

The classes to which the resource belongs to. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional)

Curl request

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

HTTP response

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

{
  "_class" : "resource",
  "classes" : [ "C3" ],
  "created_at" : "2024-07-19T14:01:08.107153833Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "extraction_method" : "UNKNOWN",
  "featured" : false,
  "formatted_label" : null,
  "id" : "R6",
  "label" : "bar",
  "modifiable" : true,
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "shared" : 0,
  "unlisted" : false,
  "verified" : false
}

Fetching a resource

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/resources/R7' -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: 497

{
  "_class" : "resource",
  "classes" : [ ],
  "created_at" : "2024-07-19T14:01:08.908255517Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "extraction_method" : "UNKNOWN",
  "featured" : false,
  "formatted_label" : null,
  "id" : "R7",
  "label" : "research contribution",
  "modifiable" : true,
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "shared" : 0,
  "unlisted" : false,
  "verified" : false
}

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: 189

{
  "error" : "Not Found",
  "message" : "Resource \"NONEXISTENT\" not found.",
  "path" : "/api/resources/NONEXISTENT",
  "status" : 404,
  "timestamp" : "2024-07-19T14:01:09.023278711Z"
}

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/R3' -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: 223

{
  "error" : "Forbidden",
  "message" : "Unable to delete resource \"R3\" because it is used in at least one statement.",
  "path" : "/api/resources/R3",
  "status" : 403,
  "timestamp" : "2024-07-19T14:01:07.485762409Z"
}

Importing a resource

The Open Research Knowledge Graph REST API provides two endpoints for importing resources from external ontologies.

Importing a resource by URI

A POST request imports a resource from an external ontology by a given URI. The response will be 201 Created when successful, even when the resource was already imported previously.

Curl request
$ curl 'https://incubating.orkg.org/api/import/resources' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "uri" : "https://www.wikidata.org/entity/Q42"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/resources/R123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

uri

String

The uri of the resource to import.

Importing a resource by short form

A POST request imports a resource from an external ontology by a given short form id. The response will be 201 Created when successful, even when the resource was already imported.

Curl request
$ curl 'https://incubating.orkg.org/api/import/resources' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "short_form" : "Q42"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/resources/R123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

short_form

String

The short form id of the resource to import.

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: 951

{
  "content" : [ {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:01:00.042950276Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P9",
    "label" : "has name",
    "modifiable" : true
  }, {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:01:00.045835505Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P10",
    "label" : "knows",
    "modifiable" : true
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}
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

id

String

The id of the predicate. (optional)

label

String

The label of the predicate.

Curl request

$ curl 'https://incubating.orkg.org/api/predicates/' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : null,
  "label" : "predicate label"
}'

HTTP response

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

{
  "_class" : "predicate",
  "created_at" : "2023-10-04T13:30:16.931457+01:00",
  "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
  "description" : null,
  "id" : "R123",
  "label" : "predicate label",
  "modifiable" : true
}

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

OffsetDateTime

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

created_by

String

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

description

String

The description of the predicate, if exists.

modifiable

Boolean

Whether this predicate can be modified.

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/P7' -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: 219

{
  "_class" : "predicate",
  "created_at" : "2024-07-19T14:00:59.828072913Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "description" : null,
  "id" : "P7",
  "label" : "yaser",
  "modifiable" : true
}

Fetching a predicate

A GET request provides information about a predicate.

Curl request

$ curl 'http://localhost:8080/api/predicates/P8' -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: 222

{
  "_class" : "predicate",
  "created_at" : "2024-07-19T14:00:59.958043564Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "description" : null,
  "id" : "P8",
  "label" : "has name",
  "modifiable" : true
}

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: 957

{
  "content" : [ {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:00:59.634112926Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P4",
    "label" : "has name",
    "modifiable" : true
  }, {
    "_class" : "predicate",
    "created_at" : "2024-07-19T14:00:59.637699025Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P5",
    "label" : "gave name to",
    "modifiable" : true
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

Importing a predicate

The Open Research Knowledge Graph REST API provides two endpoints for importing predicates from external ontologies.

Importing a predicate by URI

A POST request imports a predicate from an external ontology by a given URI.

Curl request
$ curl 'https://incubating.orkg.org/api/import/predicates' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "uri" : "https://www.wikidata.org/entity/P30"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/predicates/P123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

uri

String

The uri of the predicate to import.

The response will be 201 Created when successful, even when the predicate was already imported previously.

Importing a predicate by short form

A POST request imports a predicate from an external ontology by a given short form id. The response will be 201 Created when successful, even when the predicate was already imported previously.

Curl request
$ curl 'https://incubating.orkg.org/api/import/predicates' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "ontology" : "wikidata",
  "short_form" : "P30"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/predicates/P123
Request fields
Path Type Description

ontology

String

The identifier of the ontology. See External Sources for more information.

short_form

String

The short form id of the resource to import.

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: 1162

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

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/L481
Content-Type: application/json
Content-Length: 218

{
  "_class" : "literal",
  "created_at" : "2024-07-19T14:00:59.302384358Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "datatype" : "xs:foo",
  "id" : "L481",
  "label" : "foo",
  "modifiable" : true
}

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/L482' -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: 218

{
  "_class" : "literal",
  "created_at" : "2024-07-19T14:00:59.368241544Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "datatype" : "dt:new",
  "id" : "L482",
  "label" : "bar",
  "modifiable" : true
}

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: 238

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

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: 982

{
  "content" : [ {
    "_class" : "literal",
    "created_at" : "2024-07-19T14:00:59.132179556Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "datatype" : "xsd:string",
    "id" : "L480",
    "label" : "research topic",
    "modifiable" : true
  }, {
    "_class" : "literal",
    "created_at" : "2024-07-19T14:00:59.125957667Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "datatype" : "xsd:string",
    "id" : "L478",
    "label" : "research contribution",
    "modifiable" : true
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

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: 224

{
  "_class" : "list",
  "created_at" : "2023-10-01T16:33:19.156943+01:00",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "elements" : [ "R1" ],
  "id" : "R123",
  "label" : "List label",
  "modifiable" : true
}

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: 225

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

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.

modifiable

Boolean

Whether this list can be modified.

_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

Array

The list of DOIs of the paper. (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".

modifiable

Boolean

Whether this paper can be modified.

unlisted_by

String

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

_class

String

Indicates which type of entity was returned. Always has the value paper.

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

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (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

Object

The venue where the paper was published. (optional)

publication_info.published_in.id

String

The ID of the venue.

publication_info.published_in.label

String

The label of the venue.

publication_info.url

String

The URL to the original paper. (optional)

sdgs

Array

The list of sustainable development goals that the paper belongs to.

sdgs[].id

String

The ID of the sustainable development goal.

sdgs[].label

String

The label of the sustainable development goal.

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:

Request parameters

Parameter Description

title

A search term that must be contained in the title of the paper. (optional)

exact

Whether title matching is exact or fuzzy (optional, default: false)

doi

Filter for the DOI of the paper. (optional)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

verified

Filter for the verified flag of the paper. (optional)

created_by

Filter for the UUID of the user or service who created this paper. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned paper can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned paper can have. (optional)

observatory_id

Filter for the UUID of the observatory that the paper belongs to. (optional)

organization_id

Filter for the UUID of the organization that the paper belongs to. (optional)

research_field

Filter for research field id. (optional)

include_subfields

Flag for whether subfields are included in the search or not. (optional, default: false)

sdg

Filter for the sustainable development goal that the paper belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/papers?title=label&exact=true&doi=10.456%2F8764&visibility=ALL_LISTED&verified=true&created_by=dca4080c-e23f-489d-b900-af8bfc2b0620&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f&research_field=R456&include_subfields=true&sdg=SDG_1' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.paper.v2+json'

Fetching contributors for a paper

A GET request returns a paged list of contributor 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

Path Type Description

title

String

The title of the paper.

research_fields

Array

The list of research fields the paper will be assigned to.

identifiers

Object

The unique identifiers of the paper.

identifiers.doi

Array

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

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The set of ids of sustainable development goals the paper will be assigned to. (optional)

contents

Object

Definition of the contents of the paper.

contents.resources

Object

Definition of resources that need to be created.

contents.resources.*.label

String

The label of the resource.

contents.resources.*.classes

Array

The list of classes of the resource.

contents.literals

Object

Definition of literals that need to be created.

contents.literals.*.label

String

The value of the literal.

contents.literals.*.data_type

String

The data type of the literal.

contents.predicates

Object

Definition of predicates that need to be created.

contents.predicates.*.label

String

The label of the predicate.

contents.predicates.*.description

String

The description of the predicate.

contents.lists

Object

Definition of lists that need to be created.

contents.lists.*.label

String

The label of the list.

contents.lists.*.elements

Array

The IDs of the elements of the list.

contents.contributions

Array

List of definitions of contribution that need to be created.

contents.contributions[].label

String

Label of the contribution.

contents.contributions[].classes

Array

The classes of the contribution resource.

contents.contributions[].statements

Object

Recursive map of statements contained within the contribution.

contents.contributions[].statements.*[].id

String

The ID of the object of the statement.

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".

Curl request

$ curl 'https://incubating.orkg.org/api/papers' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.paper.v2+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "contents" : {
    "contributions" : [ {
      "classes" : [ "C123" ],
      "label" : "Contribution 1",
      "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
            } ]
          }
        } ]
      }
    } ],
    "lists" : {
      "#temp4" : {
        "elements" : [ "#temp1", "C123" ],
        "label" : "list"
      }
    },
    "literals" : {
      "#temp2" : {
        "data_type" : "xsd:decimal",
        "label" : "0.1"
      }
    },
    "predicates" : {
      "#temp3" : {
        "description" : "has result",
        "label" : "hasResult"
      }
    },
    "resources" : {
      "#temp1" : {
        "classes" : [ "Result" ],
        "label" : "MOTO"
      }
    }
  },
  "extraction_method" : "MANUAL",
  "identifiers" : {
    "doi" : [ "10.48550 / arXiv.2304.05327" ]
  },
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "publication_info" : {
    "published_in" : "conference",
    "published_month" : 5,
    "published_year" : 2015,
    "url" : "https://www.example.org"
  },
  "research_fields" : [ "R12" ],
  "sdgs" : [ "SDG_1" ],
  "title" : "example paper"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/papers/R123

Editing a paper

A PUT request updates an existing paper with all the given parameters. The response will be 204 No Content when successful. The updated paper (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, meaning that the corresponding fields should not be updated.
Author names will not be updated if a resource id is specified for a given author.

Request fields

Path Type Description

title

String

The title of the paper. (optional)

research_fields

Array

The list of research fields the paper will be assigned to. (optional)

identifiers

Object

The unique identifiers of the paper. (optional)

identifiers.doi

Array

The DOI of the paper. (optional)

publication_info

Object

The publication info of the paper. (optional)

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

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The set of ids of sustainable development goals the paper will be assigned to. (optional)

organizations[]

Array

The list of IDs of the organizations the paper belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the paper belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/papers/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.paper.v2+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "identifiers" : {
    "doi" : [ "10.48550/arXiv.2304.05327" ]
  },
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "publication_info" : {
    "published_in" : "conference",
    "published_month" : 5,
    "published_year" : 2015,
    "url" : "https://www.example.org"
  },
  "research_fields" : [ "R14" ],
  "sdgs" : [ "SDG_3", "SDG_4" ],
  "title" : "example paper"
}'

HTTP response

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

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.

authors

Array

The list of authors that originally contributed to the paper.

authors[].id

Null

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Null

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list of ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

Null

The homepage of the author. (optional)

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",
  "authors" : [ {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author 1"
  } ]
}'

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/R15634' -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: 304

{
  "classes" : [ "C123" ],
  "created_at" : "2023-11-02T10:25:05.9595396+01:00",
  "created_by" : "dca4080c-e23f-489d-b900-af8bfc2b0620",
  "extraction_method" : "MANUAL",
  "id" : "R15634",
  "label" : "Contribution",
  "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.

extraction_method

String

The method used to extract the contribution resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC".

created_at

OffsetDateTime

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

created_by

String

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

visibility

String

Visibility of the contribution. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED".

unlisted_by

String

The UUID of the user or service who unlisted this contribution.

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

extraction_method

String

The method used to extract the contribution resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (default: "UNKNOWN")

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 '{
  "contribution" : {
    "classes" : [ "C123" ],
    "label" : "Contribution 1",
    "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
          } ]
        }
      } ]
    }
  },
  "extraction_method" : "UNKNOWN",
  "lists" : {
    "#temp4" : {
      "elements" : [ "#temp1", "C123" ],
      "label" : "list"
    }
  },
  "literals" : {
    "#temp2" : {
      "data_type" : "xsd:decimal",
      "label" : "0.1"
    }
  },
  "predicates" : {
    "#temp3" : {
      "description" : "has result",
      "label" : "hasResult"
    }
  },
  "resources" : {
    "#temp1" : {
      "classes" : [ "Result" ],
      "label" : "MOTO"
    }
  }
}'

HTTP response

HTTP/1.1 201 Created
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

Array

The DOI of the comparison. (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.

versions

Array

A sorted list by creation date of previous versions of the comparison.

versions[].id

String

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

versions[].label

String

The label of a previous version of the comparison.

versions[].created_at

OffsetDateTime

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

versions[].created_by

String

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

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".

unlisted_by

String

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

_class

String

Indicates which type of entity was returned. Always has the value comparison.

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

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

publication_info

Object

The publication info of the paper.

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

Object

The venue where the comparison was published. (optional)

publication_info.published_in.id

String

The ID of the venue.

publication_info.published_in.label

String

The label of the venue.

publication_info.url

String

The URL to the original comparison. (optional)

sdgs

Array

The list of sustainable development goals that the comparison belongs to.

sdgs[].id

String

The ID of the sustainable development goal.

sdgs[].label

String

The label of the sustainable development goal.

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:

Request parameters

Parameter Description

title

A search term that must be contained in the title of the comparison. (optional)

exact

Whether title matching is exact or fuzzy (optional, default: false)

doi

Filter for the DOI of the comparison. (optional)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Filter for the UUID of the user or service who created this comparison. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional)

observatory_id

Filter for the UUID of the observatory that the resource belongs to. (optional)

organization_id

Filter for the UUID of the organization that the resource belongs to. (optional)

research_field

Filter for research field id. (optional)

include_subfields

Flag for whether subfields are included in the search or not. (optional, default: false)

sdg

Filter for the sustainable development goal that the comparison belongs to. (optional)

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.

created_at

OffsetDateTime

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

created_by

String

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

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

$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-resources' -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.

created_at

OffsetDateTime

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

created_by

String

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

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

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

Creating comparisons

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

Request fields

Path Type Description

title

String

The title of the comparison.

description

String

The description of the comparison.

research_fields

Array

The list of research fields the comparison will be assigned to.

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

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The set of ids of sustainable development goals the comparison will be assigned to. (optional)

contributions[]

Array

The ids of the contributions the comparison compares.

references[]

Array

The references to external sources that the comparison refers to.

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.

is_anonymized

Boolean

Whether or not the comparison should be displayed as anonymous.

extraction_method

String

The method used to extract the comparison resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC".

Curl request

$ curl 'https://incubating.orkg.org/api/comparisons' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "contributions" : [ "R6541", "R5364", "R9786", "R3120" ],
  "description" : "comparison description",
  "extraction_method" : "UNKNOWN",
  "is_anonymized" : false,
  "observatories" : [ "eeb1ab0f-0ef5-4bee-aba2-2d5cea2f0174" ],
  "organizations" : [ "f9965b2a-5222-45e1-8ef8-dbd8ce1f57bc" ],
  "references" : [ "https://orkg.org/resources/R1000", "paper citation" ],
  "research_fields" : [ "R12" ],
  "sdgs" : [ "SDG_1", "SDG_2" ],
  "title" : "test"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R123

Editing a comparison

A PUT request updates an existing comparison with all the given parameters. The response will be 204 No Content when successful. The updated comparison (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, meaning that the corresponding fields should not be updated.
Author names will not be updated if a resource id is specified for a given author.

Request fields

Path Type Description

title

String

The title of the comparison. (optional)

description

String

The description of the comparison. (optional)

research_fields

Array

The list of research fields the comparison will be assigned to. (optional)

authors

Array

The list of authors that originally contributed to the comparison. (optional)

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The set of ids of sustainable development goals the comparison will be assigned to. (optional)

contributions[]

Array

The ids of the contributions the comparison compares. (optional)

references[]

Array

The references to external sources that the comparison refers to. (optional)

organizations[]

Array

The list of IDs of the organizations the comparison belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the comparison belongs to. (optional)

is_anonymized

Boolean

Whether or not the comparison should be displayed as anonymous. (optional)

extraction_method

String

The method used to extract the comparison resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/comparisons/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "contributions" : [ "R6541", "R5364", "R9786", "R3120" ],
  "description" : "comparison description",
  "extraction_method" : "UNKNOWN",
  "is_anonymized" : false,
  "observatories" : [ "eeb1ab0f-0ef5-4bee-aba2-2d5cea2f0174" ],
  "organizations" : [ "f9965b2a-5222-45e1-8ef8-dbd8ce1f57bc" ],
  "references" : [ "https://orkg.org/resources/R1000", "paper citation" ],
  "research_fields" : [ "R12" ],
  "sdgs" : [ "SDG_1", "SDG_2" ],
  "title" : "test"
}'

HTTP response

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

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

Path Type Description

label

String

The label of the comparison related resource.

image

String

The url to the image of the comparison related resource. (optional)

url

String

The url of the comparison related resource. (optional)

description

String

The description of the comparison related resource. (optional)

Table 2. /api/comparisons/{comparisonId}/related-resources
Parameter Description

comparisonId

The comparison to attach the comparison related resource to.

$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-resources' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "description" : "comparison related resource description",
  "image" : "https://example.org/test.png",
  "label" : "related resource",
  "url" : "https://orkg.org/resources/R1000"
}'
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R100/related-resources/R123

A PUT request updates an existing comparison related resource with all the given parameters. The response will be 204 No Content when successful. The updated comparison related resource (object) can be retrieved by following the URI in the Location header field.

Top level fields that were mandatory when creating the comparison related resource can be omitted or null, meaning that the corresponding fields should not be updated.
Path Type Description

label

String

The label of the comparison related resource. (optional)

image

String

The url to 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.

$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-resources/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "description" : "comparison related resource description",
  "image" : "https://example.org/test.png",
  "label" : "related resource",
  "url" : "https://orkg.org/resources/R1000"
}'
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/comparisons/R100/related-resources/R123

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

Path Type Description

label

String

The label of the comparison related figure.

image

String

The url to the image of the comparison related figure. (optional)

description

String

The description of the comparison related figure. (optional)

Table 2. /api/comparisons/{comparisonId}/related-figures
Parameter Description

comparisonId

The comparison to attach the comparison related figure to.

$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-figures' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "description" : "comparison related resource description",
  "image" : "https://example.org/test.png",
  "label" : "related resource"
}'
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R100/related-figures/R123

A PUT request updates an existing comparison related figure with all the given parameters. The response will be 204 No Content when successful. The updated comparison related figure (object) can be retrieved by following the URI in the Location header field.

Top level fields that were mandatory when creating the comparison related figure can be omitted or null, meaning that the corresponding fields should not be updated.
Path Type Description

label

String

The label of the comparison related figure. (optional)

image

String

The url to the image of the comparison related figure.

description

String

The description of the comparison related figure.

$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-figures/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.comparison.v2+json' \
    -d '{
  "description" : "comparison related resource description",
  "image" : "https://example.org/test.png",
  "label" : "related resource"
}'
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/comparisons/R100/related-figures/R123

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.

authors

Array

The list of authors that originally contributed to the comparison.

authors[].id

Null

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Null

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

Null

The homepage of the author. (optional)

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",
  "authors" : [ {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author 1"
  } ]
}'

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.

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".

unlisted_by

String

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

_class

String

Indicates which type of entity was returned. Always has the value 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

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

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:

Not all request parameters can be used in combination with others. Only visibility, research_field and optionally include_subfields can be used together.

Request parameters

Parameter Description

title

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

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Optional filter for the UUID of the user or service who created the visualization.

research_field

Optional filter for research field id.

include_subfields

Optional flag for whether subfields are included in the search or not.

Creating visualizations

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

Request fields

Path Type Description

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

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs 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".

Curl request

$ curl 'https://incubating.orkg.org/api/visualizations' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.visualization.v2+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "description" : "visualization description",
  "extraction_method" : "UNKNOWN",
  "observatories" : [ "eeb1ab0f-0ef5-4bee-aba2-2d5cea2f0174" ],
  "organizations" : [ "f9965b2a-5222-45e1-8ef8-dbd8ce1f57bc" ],
  "title" : "test"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/visualizations/R123

Literature Lists

Literature Lists 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 literature list 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 literature list

A GET request provides information about a literature list.

Curl request

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

Response fields

Path Type Description

id

String

The identifier of the literature list.

title

String

The title of the literature list.

research_fields

Array

The list of research fields the literature list is assigned to.

research_fields[].id

String

The id of the research field.

research_fields[].label

String

The label of the research field.

versions.head

Object

The head version of the literature list.

versions.head.id

String

The id of the head version.

versions.head.label

String

The label of the head version.

versions.head.created_at

OffsetDateTime

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

versions.head.created_by

String

The UUID of the user or service who created the literature list version.

versions.published

Array

The list of published versions of the literature list.

versions.published[].id

String

The id of the published version.

versions.published[].label

String

The label of the published version.

versions.published[].created_at

OffsetDateTime

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

versions.published[].created_by

String

The UUID of the user or service who created the literature list version.

versions.published[].changelog

String

The changelog of the published version.

organizations[]

Array

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

observatories[]

Array

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

extraction_method

String

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

created_at

OffsetDateTime

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

created_by

String

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

visibility

String

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

unlisted_by

String

The UUID of the user or service who unlisted this literature list.

published

Boolean

Whether the literature is published or not.

sections

Array

The list of sections of the literature list.

sections[].id

String

The id of the section.

sections[].type

String

The type of the section. Either of "text" or "list".

sections[].entries

Array

The linked resources of a list section.

sections[].entries[].value

Object

The linked resource of the entry.

sections[].entries[].value.id

String

The id of the linked resource.

sections[].entries[].value.label

String

The label of the linked resource.

sections[].entries[].value.classes

Array

The classes of the linked resource.

sections[].entries[].value._class

Varies

Indicates which type of entity was returned. Always has the value resource_ref.

sections[].entries[].description

String

The description of the entry.

sections[].heading

String

The heading of the text section.

sections[].heading_size

Number

The heading size of the text section.

sections[].text

String

The text contents of the text section.

acknowledgements

Object

A key-value map of contributor ids to an estimated contribution percentage.

_class

String

Indicates which type of entity was returned. Always has the value literature-list.

authors

Array

The list of authors that originally contributed to the literature list.

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

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The list of sustainable development goals that the literature list belongs to.

sdgs[].id

String

The ID of the sustainable development goal.

sdgs[].label

String

The label of the sustainable development goal.

Listing literature lists

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

Curl request

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

The following list of request parameters are supported:

Request parameters

Parameter Description

title

A search term that must be contained in the title of the literature list. (optional)

exact

Whether title matching is exact or fuzzy (optional, default: false)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Filter for the UUID of the user or service who created this literature list. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional)

observatory_id

Filter for the UUID of the observatory that the resource belongs to. (optional)

organization_id

Filter for the UUID of the organization that the resource belongs to. (optional)

published

Filter for the publication status of the literature lists. (optional)

sdg

Filter for the sustainable development goal that the literature list belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/literature-lists?title=label&exact=true&visibility=ALL_LISTED&created_by=46a2e212-014c-4e8f-95eb-1c54118de482&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=5c47d93a-244e-4928-a375-6049f4e63bec&organization_id=1cc8407f-997e-423e-b706-3ea6d2af09f7&published=true&sdg=SDG_1' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list.v1+json'

Creating literature lists

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

Request fields

Path Type Description

title

String

The title of the literature list.

research_fields

Array

The list of research fields the literature list will be assigned to.

sdgs

Array

The set of ids of sustainable development goals the literature list will be assigned to. (optional)

organizations[]

Array

The list of IDs of the organizations the literature list belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the literature list belongs to. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN")

sections

Array

The list of updated sections of the literature list (optional). See literature list sections for more information.

authors

Array

The list of authors that originally contributed to the literature list.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/literature-lists' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list.v1+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "extraction_method" : "MANUAL",
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "research_fields" : [ "R14" ],
  "sdgs" : [ "SDG_3", "SDG_4" ],
  "sections" : [ {
    "heading" : "heading",
    "heading_size" : 1,
    "text" : "text contents"
  }, {
    "entries" : [ {
      "description" : "Example description of an entry",
      "id" : "R123"
    }, {
      "description" : null,
      "id" : "R456"
    } ]
  } ],
  "title" : "Dummy Literature List Label"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/literature-lists/R123

Editing a literature list

A PUT request updates an existing literature list with all the given parameters. The response will be 204 No Content when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, meaning that the corresponding fields should not be updated.
Author names will not be updated if a resource id is specified for a given author.

Request fields

Path Type Description

title

String

The title of the literature list. (optional)

research_fields

Array

The list of research fields the literature list will be assigned to. (optional)

sdgs

Array

The set of ids of sustainable development goals the literature list will be assigned to. (optional)

organizations[]

Array

The list of IDs of the organizations the literature list belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the literature list belongs to. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN")

sections

Array

The list of updated sections of the literature list (optional). See literature list sections for more information.

authors

Array

The list of authors that originally contributed to the literature list.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/literature-lists/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list.v1+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "extraction_method" : "MANUAL",
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "research_fields" : [ "R14" ],
  "sdgs" : [ "SDG_3", "SDG_4" ],
  "sections" : [ {
    "heading" : "heading",
    "heading_size" : 1,
    "text" : "text contents"
  }, {
    "entries" : [ {
      "description" : "Example description of an entry",
      "id" : "R123"
    }, {
      "description" : null,
      "id" : "R456"
    } ]
  } ],
  "title" : "Dummy Literature List Label"
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/literature-lists/R123

Fetching published literature list contents

A GET request returns contents of an already published literature list, at the state of publishing.

Curl request

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

Depending on the type of the requested content, the following representations are returned:

Type Returned Representation

Dataset

Resource

Paper

Paper

Software

Resource

Literature List Sections

Literature Lists Sections represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They are used to define the contents of a literature list. The provided endpoints aggregate these concepts into a literature list section 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.

Text Sections

Creating a text section

A POST request creates a new text section and adds it to the specified literature list. The response will be 201 Created when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.literature-list-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list-section.v1+json' \
    -d '{
  "heading" : "heading",
  "heading_size" : 2,
  "text" : "text contents"
}'
Path parameters
Table 2. /api/literature-lists/{literatureListId}/sections/{index}
Parameter Description

literatureListId

The id of the literature list to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created text section will be appended at the end of the literature list. (optional)

Request fields
Path Type Description

heading

String

The heading of the text section.

heading_size

Number

The heading size of the text section.

text

String

The text contents of the text section.

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/literature-lists/R3541

Editing a text section

A PUT request updates an existing text section with all the given parameters. The response will be 204 No Content when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the text section.

heading_size

Number

The updated heading size of the text section.

text

String

The updated text contents of the text section.

Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.literature-list-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list-section.v1+json' \
    -d '{
  "heading" : "updated heading",
  "heading_size" : 3,
  "text" : "updated text contents"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/literature-lists/R3541

List Sections

Creating a list section

A POST request creates a new list section and adds it to the specified literature list. The response will be 201 Created when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.literature-list-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list-section.v1+json' \
    -d '{
  "entries" : [ {
    "description" : null,
    "id" : "R123"
  }, {
    "description" : null,
    "id" : "R456"
  } ]
}'
Path parameters
Table 2. /api/literature-lists/{literatureListId}/sections/{index}
Parameter Description

literatureListId

The id of the literature list to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created list section will be appended at the end of the literature list. (optional)

Request fields
Path Type Description

entries

Array

The list entries that should be part of this section.

entries[].id

String

The id of the linked resource. Every resource must either be an instance of "Paper", "Dataset" or "Software".

entries[].description

Null

The description of the entry. (optional)

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/literature-lists/R3541

Editing a list section

A PUT request updates an existing list section with all the given parameters. The response will be 204 No Content when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

entries

Array

The list of updated entries that should be part of this section.

entries[].id

String

The id of the linked resource. Every resource must either be an instance of "Paper", "Dataset" or "Software".

entries[].description

Null

The description of the entry. (optional)

Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.literature-list-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list-section.v1+json' \
    -d '{
  "entries" : [ {
    "description" : null,
    "id" : "R123"
  }, {
    "description" : null,
    "id" : "R456"
  } ]
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/literature-lists/R3541

Deleting a literature list section

A DELETE request deletes a literature list section by ID. The response will be 204 No Content when successful. The updated literature list (object) can be retrieved by following the URI in the Location header field.

Curl request

$ curl 'https://incubating.orkg.org/api/literature-lists/R3541/sections/R123' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.literature-list-section.v1+json'

Path parameters

Table 2. /api/literature-lists/{literatureListId}/sections/{sectionId}
Parameter Description

literatureListId

The id of the literature list the section belongs to.

sectionId

The id of the section.

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/literature-lists/R3541

Smart Reviews

Smart Reviews 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 smart review 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 smart review

A GET request provides information about a smart review.

Curl request

$ curl 'https://incubating.orkg.org/api/smart-reviews/R1456' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review.v1+json'

Response fields

Path Type Description

id

String

The identifier of the smart review.

title

String

The title of the smart review.

research_fields

Array

The list of research fields the smart review is assigned to.

research_fields[].id

String

The id of the research field.

research_fields[].label

String

The label of the research field.

versions.head

Object

The head version of the smart review.

versions.head.id

String

The id of the head version.

versions.head.label

String

The label of the head version.

versions.head.created_at

OffsetDateTime

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

versions.head.created_by

String

The UUID of the user or service who created the smart review version.

versions.published

Array

The list of published versions of the smart review.

versions.published[].id

String

The id of the published version.

versions.published[].label

String

The label of the published version.

versions.published[].created_at

OffsetDateTime

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

versions.published[].created_by

String

The UUID of the user or service who created the review version version.

versions.published[].changelog

String

The changelog of the published version.

organizations[]

Array

The list of IDs of the organizations the smart review belongs to.

observatories[]

Array

The list of IDs of the observatories the smart review belongs to.

extraction_method

String

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

created_at

OffsetDateTime

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

created_by

String

The UUID of the user or service who created this smart review.

visibility

String

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

unlisted_by

String

The UUID of the user or service who unlisted this smart review.

published

Boolean

Whether the literature is published or not.

sections

Array

The list of sections of the smart review.

sections[].id

String

The id of the section.

sections[].heading

String

The heading of the section.

sections[].type

String

The type of the section. Either of "text", "comparison", "visualization", "resource", "property" or "ontology".

sections[].comparison

Object

The linked comparison of a comparison section.

sections[].comparison.id

String

The id of the linked comparison.

sections[].comparison.label

String

The label of the linked comparison.

sections[].comparison.classes

Array

The classes of the linked comparison.

sections[].comparison._class

String

Indicates which type of entity was returned. Always has the value resource_ref.

sections[].visualization

Object

The linked visualization of a visualization section.

sections[].visualization.id

String

The id of the linked visualization.

sections[].visualization.label

String

The label of the linked visualization.

sections[].visualization.classes

Array

The classes of the linked visualization.

sections[].visualization._class

String

Indicates which type of entity was returned. Always has the value resource_ref.

sections[].resource

Object

The linked resource of a resource section.

sections[].resource.id

String

The id of the linked resource.

sections[].resource.label

String

The label of the linked resource.

sections[].resource.classes

Array

The classes of the linked resource.

sections[].resource._class

String

Indicates which type of entity was returned. Always has the value resource_ref.

sections[].predicate

Object

The linked resource of a predicate section.

sections[].predicate.id

String

The id of the linked predicate.

sections[].predicate.label

String

The label of the linked predicate.

sections[].predicate._class

String

Indicates which type of entity was returned. Always has the value predicate_ref.

sections[].entities

Array

The entities that should be shown in the ontology section. They can either be a resource or a predicate.

sections[].entities[].id

String

The id of the entity.

sections[].entities[].label

String

The label of the entity.

sections[].entities[].classes

Array

The classes of the entity, if the entity is a resource.

sections[].entities[]._class

String

Indicates which type of entity was returned. Always has the value resource_ref.

sections[].predicates

Array

The predicates that should be shown in the ontology section.

sections[].predicates[].id

String

The id of the predicate.

sections[].predicates[].label

String

The label of the predicate.

sections[].predicates[]._class

String

Indicates which type of entity was returned. Always has the value predicate_ref.

sections[].text

String

The text contents of the text section.

sections[].classes

Array

The additional classes of the text section.

references

Array

The list of bibtex references of the smart review.

acknowledgements

Object

A key-value map of contributor ids to an estimated contribution percentage.

_class

String

Indicates which type of entity was returned. Always has the value smart-review.

authors

Array

The list of authors that originally contributed to the smart review.

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

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

sdgs

Array

The list of sustainable development goals that the smart review belongs to.

sdgs[].id

String

The ID of the sustainable development goal.

sdgs[].label

String

The label of the sustainable development goal.

Listing smart reviews

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

Curl request

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

The following list of request parameters are supported:

Request parameters

Parameter Description

title

A search term that must be contained in the title of the smart review. (optional)

exact

Whether title matching is exact or fuzzy (optional, default: false)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Filter for the UUID of the user or service who created this smart review. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional)

observatory_id

Filter for the UUID of the observatory that the resource belongs to. (optional)

organization_id

Filter for the UUID of the organization that the resource belongs to. (optional)

published

Filter for the publication status of the smart reviews. (optional)

sdg

Filter for the sustainable development goal that the smart review belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/smart-reviews?title=label&exact=true&visibility=ALL_LISTED&created_by=beeda847-6359-4196-bbde-432cd0f71e41&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=38d5fdc5-7895-4b5e-a0db-7fd7b85cbea6&organization_id=d8dfd0be-0556-4205-b8ed-70975c4ba81d&published=true&sdg=SDG_1' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review.v1+json'

Creating smart reviews

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

Request fields

Path Type Description

title

String

The title of the smart review.

research_fields

Array

The list of research fields the smart review will be assigned to.

sdgs

Array

The set of ids of sustainable development goals the smart review will be assigned to. (optional)

organizations[]

Array

The list of IDs of the organizations the smart review belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the smart review belongs to. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN")

sections

Array

The list of sections of the smart review. See smart review sections for more information.

references[]

Array

The list of bibtex references of the smart review.

authors

Array

The list of authors that originally contributed to the smart review.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/smart-reviews' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review.v1+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "extraction_method" : "MANUAL",
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "references" : [ "reference 1", "reference 2" ],
  "research_fields" : [ "R14" ],
  "sdgs" : [ "SDG_3", "SDG_4" ],
  "sections" : [ {
    "comparison" : "comparisonId",
    "heading" : "comparison section heading"
  }, {
    "heading" : "visualization section heading",
    "visualization" : "visualizationId"
  }, {
    "heading" : "resource section heading",
    "resource" : "resourceId"
  }, {
    "heading" : "predicate section heading",
    "predicate" : "predicateId"
  }, {
    "entities" : [ "resourceId" ],
    "heading" : "ontology section heading",
    "predicates" : [ "predicateId" ]
  }, {
    "class" : "Epilogue",
    "heading" : "text section heading",
    "text" : "epilogue"
  } ],
  "title" : "Dummy Smart Review Label"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R123

Editing a smart review

A PUT request updates an existing smart review with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, meaning that the corresponding fields should not be updated.
Author names will not be updated if a resource id is specified for a given author.

Request fields

Path Type Description

title

String

The title of the smart review. (optional)

research_fields

Array

The list of research fields the smart review will be assigned to. (optional)

sdgs

Array

The set of ids of sustainable development goals the smart review will be assigned to. (optional)

organizations[]

Array

The list of IDs of the organizations the smart review belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the smart review belongs to. (optional)

extraction_method

String

The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN")

sections

Array

The list of updated sections of the smart review (optional). See smart review sections for more information.

references[]

Array

The list of updated bibtex references of the smart review.

authors

Array

The list of authors that originally contributed to the smart review.

authors[].id

String

The ID of the author. (optional)

authors[].name

String

The name of the author.

authors[].identifiers

Varies

The unique identifiers of the author.

authors[].identifiers.orcid

Array

The list ORCIDs of the author. (optional)

authors[].identifiers.google_scholar

Array

The list of Google Scholar IDs of the author. (optional)

authors[].identifiers.research_gate

Array

The list of ResearchGate IDs of the author. (optional)

authors[].identifiers.linked_in

Array

The list of LinkedIn IDs of the author. (optional)

authors[].identifiers.wikidata

Array

The list of Wikidata IDs of the author. (optional)

authors[].identifiers.web_of_science

Array

The list of Web of Science IDs of the author. (optional)

authors[].homepage

String

The homepage of the author. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/smart-reviews/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review.v1+json' \
    -d '{
  "authors" : [ {
    "homepage" : null,
    "id" : "R123",
    "identifiers" : null,
    "name" : "Author with id"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : {
      "orcid" : [ "0000-1111-2222-3333" ]
    },
    "name" : "Author with orcid"
  }, {
    "homepage" : null,
    "id" : "R456",
    "identifiers" : {
      "orcid" : [ "1111-2222-3333-4444" ]
    },
    "name" : "Author with id and orcid"
  }, {
    "homepage" : "http://example.org/author",
    "id" : null,
    "identifiers" : null,
    "name" : "Author with homepage"
  }, {
    "homepage" : null,
    "id" : null,
    "identifiers" : null,
    "name" : "Author that just has a name"
  } ],
  "extraction_method" : "MANUAL",
  "observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
  "organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
  "references" : [ "updated reference 1", "updated reference 2" ],
  "research_fields" : [ "R14" ],
  "sdgs" : [ "SDG_3", "SDG_4" ],
  "sections" : [ {
    "comparison" : "comparisonId",
    "heading" : "comparison section heading"
  }, {
    "heading" : "visualization section heading",
    "visualization" : "visualizationId"
  }, {
    "heading" : "resource section heading",
    "resource" : "resourceId"
  }, {
    "heading" : "predicate section heading",
    "predicate" : "predicateId"
  }, {
    "entities" : [ "resourceId" ],
    "heading" : "ontology section heading",
    "predicates" : [ "predicateId" ]
  }, {
    "class" : "Epilogue",
    "heading" : "text section heading",
    "text" : "epilogue"
  } ],
  "title" : "Dummy Smart Review Label"
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R123

Smart Review Sections

Smart Reviews Sections represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They are used to define the contents of a smart review. The provided endpoints aggregate these concepts into a smart review section 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.

Comparison Sections

Creating a comparison section

A POST request creates a new comparison section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "comparison" : "comparisonId",
  "heading" : "comparison section heading"
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created comparison section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the comparison section.

comparison

String

The id of the linked comparison. (optional)

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a comparison section

A PUT request updates an existing comparison section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the comparison section.

comparison

String

The updated id of the linked comparison.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "comparison" : "comparisonId",
  "heading" : "comparison section heading"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Visualization Sections

Creating a visualization section

A POST request creates a new visualization section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "visualization section heading",
  "visualization" : "visualizationId"
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created visualization section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the visualization section.

visualization

String

The id of the linked visualization. (optional)

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a visualization section

A PUT request updates an existing visualization section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the visualization section.

visualization

String

The updated id of the linked visualization.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "visualization section heading",
  "visualization" : "visualizationId"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Resource Sections

Creating a resource section

A POST request creates a new resource section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "resource section heading",
  "resource" : "resourceId"
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created resource section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the resource section.

resource

String

The id of the linked resource. (optional)

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a resource section

A PUT request updates an existing resource section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the resource section.

resource

String

The updated id of the linked resource.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "resource section heading",
  "resource" : "resourceId"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Predicate Sections

Creating a predicate section

A POST request creates a new predicate section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "predicate section heading",
  "predicate" : "predicateId"
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created predicate section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the predicate section.

predicate

String

The id of the linked predicate. (optional)

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a predicate section

A PUT request updates an existing predicate section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the predicate section.

predicate

String

The updated id of the linked predicate. (optional)

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "heading" : "predicate section heading",
  "predicate" : "predicateId"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Ontology Sections

Creating an ontology section

A POST request creates a new ontology section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "entities" : [ "resourceId" ],
  "heading" : "ontology section heading",
  "predicates" : [ "predicateId" ]
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created ontology section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the ontology section.

entities[]

Array

The id of the entities that should be shown in the ontology section.

predicates[]

Array

The ids of the predicates that should be shown in the ontology section.

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a ontology section

A PUT request updates an existing ontology section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the ontology section.

entities[]

Array

The updated id of the entities that should be shown in the ontology section.

predicates[]

Array

The updated ids of the predicates that should be shown in the ontology section.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "entities" : [ "resourceId" ],
  "heading" : "ontology section heading",
  "predicates" : [ "predicateId" ]
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Text Sections

Creating a text section

A POST request creates a new text section and adds it to the specified smart review. The response will be 201 Created when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/5' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "class" : "Epilogue",
  "heading" : "text section heading",
  "text" : "epilogue"
}'
Path parameters
Table 2. /api/smart-reviews/{smartReviewId}/sections/{index}
Parameter Description

smartReviewId

The id of the smart review to which the new section should be appended to.

index

The insertion index the of the section. Otherwise, the created text section will be appended at the end of the smart review. (optional)

Request fields
Path Type Description

heading

String

The heading of the text section.

text

String

The text contents of the text section.

class

String

The id of the class that indicates the type of the text section.

HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Editing a text section

A PUT request updates an existing text section with all the given parameters. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

heading

String

The updated heading of the text section.

text

String

The updated text contents of the text section.

class

String

The updated id of the class that indicates the type of the text section.

Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.smart-review-section.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json' \
    -d '{
  "class" : "Epilogue",
  "heading" : "text section heading",
  "text" : "epilogue"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Deleting a smart review section

A DELETE request deletes a smart review section by ID. The response will be 204 No Content when successful. The updated smart review (object) can be retrieved by following the URI in the Location header field.

Curl request

$ curl 'https://incubating.orkg.org/api/smart-reviews/R3541/sections/R123' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.smart-review-section.v1+json'

Path parameters

Table 2. /api/smart-reviews/{smartReviewId}/sections/{sectionId}
Parameter Description

smartReviewId

The id of the smart review the section belongs to.

sectionId

The id of the section.

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/smart-reviews/R3541

Templates

Templates represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They can be used to define structures to research contribution data and can help illustrate what kind of data is needed to make the paper comparable. The provided endpoints aggregate these concepts into a template 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 template

A GET request provides information about a template.

Curl request

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

Response fields

Path Type Description

id

String

The identifier of the template.

label

String

The label of the template.

description

String

The description of the template.

formatted_label

String

The formatted label pattern of the template.

target_class

Object

The target class of the template.

target_class.id

String

The id of the target class.

target_class.label

String

The label of the target class.

target_class.uri

String

The uri of the target class. (optional)

target_class._class

String

Indicates which type of entity was returned. Always has the value class_ref.

relations

Object

The relations class of the template. Used for suggestions.

relations.research_fields[]

Array

The research fields that this template relates to.

relations.research_fields[].id

String

The id of the research field that this template relates to.

relations.research_fields[].label

String

The label of the research field that this template relates to.

relations.research_problems[]

Array

The research problems that this template relates to.

relations.research_problems[].id

String

The id of the research problem that this template relates to.

relations.research_problems[].label

String

The label of the research problem that this template relates to.

relations.predicate

Object

The predicate that this template relates to. (optional)

relations.predicate.id

String

The id of the predicate that this template relates to.

relations.predicate.label

String

The label of the predicate that this template relates to.

properties

Array

The list of properties of the template. See template properties for more information.

is_closed

Boolean

Whether the template is closed or not. When a template is closed, its properties cannot be modified.

organizations[]

Array

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

observatories[]

Array

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

created_at

OffsetDateTime

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

created_by

String

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

visibility

String

Visibility of the template. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED".

unlisted_by

String

The UUID of the user or service who unlisted this template.

_class

String

Indicates which type of entity was returned. Always has the value template.

Listing templates

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

Curl request

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

The following list of request parameters are supported:

Request parameters

Parameter Description

q

A search term that must be contained in the label of the template. (optional).

exact

Whether label matching is exact or fuzzy (optional, default: false)

visibility

Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional)

created_by

Filter for the UUID of the user or service who created the template. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned template can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned template can have. (optional)

observatory_id

Filter for the UUID of the observatory that the template belongs to. (optional)

organization_id

Filter for the UUID of the organization that the template belongs to. (optional)

research_field

Filter for research field id. (optional)

include_subfields

Flag for whether subfields are included in the search or not. (optional, default: false)

research_problem

Filter for related research problem id. (optional)

target_class

Filter for the target class. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/templates?q=label&exact=true&visibility=ALL_LISTED&created_by=dca4080c-e23f-489d-b900-af8bfc2b0620&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f&research_field=R456&include_subfields=true&research_problem=R789&target_class=targetClass' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.v1+json'

Creating templates

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

Request fields

Path Type Description

label

String

The label of the template.

description

String

The description of the template.

formatted_label

String

The formatted label pattern of the template. (optional)

target_class

String

The target class of the template.

relations

Object

The related resources of the template. This is used for suggestions.

relations.research_fields[]

Array

The list of research fields the template relates to.

relations.research_problems[]

Array

The list of research problems the template relates to.

relations.predicate

String

The predicate the template relates to.

properties

Array

The list of properties of the template. See template properties for more information.

is_closed

Boolean

Whether the template is closed or not. When a template is closed, its properties cannot be modified.

organizations[]

Array

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

observatories[]

Array

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

Curl request

$ curl 'https://incubating.orkg.org/api/templates' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.v1+json' \
    -d '{
  "description" : "Some description about the template",
  "formatted_label" : "{P32}",
  "is_closed" : true,
  "label" : "Dummy Template Label",
  "observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "properties" : [ {
    "description" : "property description",
    "label" : "property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "property placeholder"
  }, {
    "datatype" : "String",
    "description" : "string literal property description",
    "label" : "string literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "pattern" : "\\d+",
    "placeholder" : "string literal property placeholder"
  }, {
    "datatype" : "Integer",
    "description" : "number literal property description",
    "label" : "number literal property label",
    "max_count" : 2,
    "max_inclusive" : 10,
    "min_count" : 1,
    "min_inclusive" : 5,
    "path" : "P24",
    "placeholder" : "number literal property placeholder"
  }, {
    "datatype" : "C25",
    "description" : "literal property description",
    "label" : "literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "literal property placeholder"
  }, {
    "class" : "C28",
    "description" : "resource property description",
    "label" : "resource property label",
    "max_count" : 4,
    "min_count" : 3,
    "path" : "P27",
    "placeholder" : "resource property placeholder"
  } ],
  "relations" : {
    "predicate" : "P22",
    "research_fields" : [ "R20" ],
    "research_problems" : [ "R21" ]
  },
  "target_class" : "targetClass"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R123

Editing a template

A PUT request updates an existing template with all the given parameters. The response will be 204 No Content when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields such as formatted_label, meaning that the corresponding fields should not be updated.

Request fields

Path Type Description

label

String

The label of the template. (optional)

description

String

The description of the template. (optional)

formatted_label

String

The formatted label pattern of the template.

target_class

String

The target class of the template. (optional)

relations

Object

The related resources of the template. This is used for suggestions. (optional)

relations.research_fields[]

Array

The list of research fields the template relates to.

relations.research_problems[]

Array

The list of research problems the template relates to.

relations.predicate

String

The predicate the template relates to.

properties

Array

The list of updated properties of the template (optional). See template properties for more information.

is_closed

Boolean

Whether the template is closed or not. When a template is closed, its properties cannot be modified. (optional)

organizations[]

Array

The list of IDs of the organizations the template belongs to. (optional)

observatories[]

Array

The list of IDs of the observatories the template belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/templates/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.v1+json' \
    -d '{
  "description" : "Some description about the template",
  "formatted_label" : "{P32}",
  "is_closed" : true,
  "label" : "Dummy Template Label",
  "observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "properties" : [ {
    "description" : "property description",
    "label" : "property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "property placeholder"
  }, {
    "datatype" : "String",
    "description" : "string literal property description",
    "label" : "string literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "pattern" : "\\d+",
    "placeholder" : "string literal property placeholder"
  }, {
    "datatype" : "Integer",
    "description" : "number literal property description",
    "label" : "number literal property label",
    "max_count" : 2,
    "max_inclusive" : 10,
    "min_count" : 1,
    "min_inclusive" : 5,
    "path" : "P24",
    "placeholder" : "number literal property placeholder"
  }, {
    "datatype" : "C25",
    "description" : "literal property description",
    "label" : "literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "literal property placeholder"
  }, {
    "class" : "C28",
    "description" : "resource property description",
    "label" : "resource property label",
    "max_count" : 4,
    "min_count" : 3,
    "path" : "P27",
    "placeholder" : "resource property placeholder"
  } ],
  "relations" : {
    "predicate" : "P22",
    "research_fields" : [ "R20" ],
    "research_problems" : [ "R21" ]
  },
  "target_class" : "targetClass"
}'

HTTP response

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

Template Properties

Template properties represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They can be used to define constraints for a single value of a template. The provided endpoints aggregate these concepts into a template property 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.

Untyped template properties

Creating an untyped template property

A POST request creates a new template property without any type constraints. The response will be 201 Created when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property. (optional)

description

String

The description of the property. (optional)

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional)

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional)

path

String

The predicate id for the path of the property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "description" : "property description",
  "label" : "property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "placeholder" : "property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541

Editing an untyped template property

A PUT request updates an existing template property of any type with all the given parameters and converts it to an untyped template property if necessary. If the previous template property had a type constraint, it will be removed in the process. The response will be 204 No Content when successful. The updated template property (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields, meaning that the corresponding fields should not be updated.
Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property.

description

String

The description of the property.

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality.

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count.

path

String

The predicate id for the path of the property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "description" : "property description",
  "label" : "property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "placeholder" : "property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541

Literal template properties

Creating a literal template property

A POST request creates a new literal template property for the given datatype, without any additional constraints. The response will be 201 Created when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property. (optional)

description

String

The description of the property. (optional)

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional)

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional)

path

String

The predicate id for the path of the property.

datatype

String

The class id of the datatype of the property, indicating a literal property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "datatype" : "C25",
  "description" : "literal property description",
  "label" : "literal property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "placeholder" : "literal property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541

Editing a literal template property

A PUT request updates an existing template property of any type with all the given parameters and converts it to a literal template property if necessary. The response will be 204 No Content when successful. The updated template property (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields, meaning that the corresponding fields should not be updated.
Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property.

description

String

The description of the property.

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality.

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count.

path

String

The predicate id for the path of the property.

datatype

String

The class id of the datatype of the property, indicating a literal property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "datatype" : "C25",
  "description" : "literal property description",
  "label" : "literal property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "placeholder" : "literal property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541

String literal template properties

Creating a string literal template property

A POST request creates a new string template property, with an optional pattern constraint. The response will be 201 Created when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property. (optional)

description

String

The description of the property. (optional)

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional)

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional)

path

String

The predicate id for the path of the property.

pattern

String

The pattern (regular expression) of the property. (optional)

datatype

String

The class id of the datatype of the property. Must be "String".

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "datatype" : "String",
  "description" : "string literal property description",
  "label" : "string literal property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "pattern" : "\\d+",
  "placeholder" : "string literal property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541

Editing a string literal template property

A PUT request updates an existing template property of any type with all the given parameters and converts it to a string literal template property if necessary. The response will be 204 No Content when successful. The updated template property (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields, meaning that the corresponding fields should not be updated.
Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property.

description

String

The description of the property.

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality.

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count.

path

String

The predicate id for the path of the property.

pattern

String

The pattern (regular expression) of the property.

datatype

String

The class id of the datatype of the property. Must be "String".

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "datatype" : "String",
  "description" : "string literal property description",
  "label" : "string literal property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "pattern" : "\\d+",
  "placeholder" : "string literal property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541

Number literal template properties

Creating a number literal template property

A POST request creates a new number template property, with optional boundary constraints. The response will be 201 Created when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property. (optional)

description

String

The description of the property. (optional)

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional)

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional)

path

String

The predicate id for the path of the property.

min_inclusive

Number

The minimum value (inclusive) that the number can have (optional).

max_inclusive

Number

The maximum value (inclusive) that the number can have (optional).

datatype

String

The class id of the datatype of the property. Must be either of "Integer", "Decimal" or "Float".

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "datatype" : "Integer",
  "description" : "number literal property description",
  "label" : "number literal property label",
  "max_count" : 2,
  "max_inclusive" : 10,
  "min_count" : 1,
  "min_inclusive" : 5,
  "path" : "P24",
  "placeholder" : "number literal property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541

Editing a number literal template property

A PUT request updates an existing template property of any type with all the given parameters and converts it to a number literal template property if necessary. The response will be 204 No Content when successful. The updated template property (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields, meaning that the corresponding fields should not be updated.
Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property.

description

String

The description of the property.

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality.

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count.

path

String

The predicate id for the path of the property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "description" : "property description",
  "label" : "property label",
  "max_count" : 2,
  "min_count" : 1,
  "path" : "P24",
  "placeholder" : "property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541

Resource template properties

Creating a resource template property

A POST request creates a new resource template property for the given datatype, without any additional constraints. The response will be 201 Created when successful. The updated template (object) can be retrieved by following the URI in the Location header field.

Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property. (optional)

description

String

The description of the property. (optional)

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional)

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional)

path

String

The predicate id for the path of the property.

class

String

The class id of the range of the property, indicating a resource property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "class" : "C28",
  "description" : "resource property description",
  "label" : "resource property label",
  "max_count" : 4,
  "min_count" : 3,
  "path" : "P27",
  "placeholder" : "resource property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541

Editing a resource template property

A PUT request updates an existing template property of any type with all the given parameters and converts it to a resource template property if necessary. The response will be 204 No Content when successful. The updated template property (object) can be retrieved by following the URI in the Location header field.

All fields at the top level in the request can be omitted or null, except for optional fields, meaning that the corresponding fields should not be updated.
Request fields
Path Type Description

label

String

The label of the property.

placeholder

String

The placeholder of the property.

description

String

The description of the property.

min_count

Number

The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality.

max_count

Number

The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count.

path

String

The predicate id for the path of the property.

class

String

The class id of the range of the property, indicating a resource property.

Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template.property.v1+json' \
    -d '{
  "class" : "C28",
  "description" : "resource property description",
  "label" : "resource property label",
  "max_count" : 4,
  "min_count" : 3,
  "path" : "P27",
  "placeholder" : "resource property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541

Template Instances

Template instances are an abstraction for a subgraph of statements, which is defined by a template.

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 template instance

A GET request provides information about a template instance.

Curl request

$ curl 'https://incubating.orkg.org/api/templates/R132/instances/R54631' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template-instance.v1+json'

Response fields

Path Type Description

root

Object

The resource representation of the root resource.

statements

Object

Map of predicate id to list of embedded statement representations, where root is the subject.

statements.*[].thing

Object

The thing representation of the object of the statement. Acts as the subject for statements defined in the statements object.

statements.*[].created_at

OffsetDateTime

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

statements.*[].created_by

String

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

statements.*[].statements

Object

Map of predicate id to list of embedded statement representations, where thing is the subject.

HTTP response

HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.template-instance.v1+json
Content-Length: 3235

{
  "root" : {
    "_class" : "resource",
    "classes" : [ "targetClass" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R54631",
    "label" : "Default Label",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 0,
    "unlisted" : false,
    "verified" : false
  },
  "statements" : {
    "P24" : [ {
      "created_at" : "2023-10-03T14:31:17.365491+01:00",
      "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
      "statements" : { },
      "thing" : {
        "_class" : "literal",
        "created_at" : "2023-10-03T14:31:17.365491+01:00",
        "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
        "datatype" : "xsd:string",
        "id" : "L1",
        "label" : "untyped",
        "modifiable" : true
      }
    } ],
    "description" : [ {
      "created_at" : "2023-10-03T14:31:17.365491+01:00",
      "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
      "statements" : { },
      "thing" : {
        "_class" : "literal",
        "created_at" : "2023-10-03T14:31:17.365491+01:00",
        "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
        "datatype" : "xsd:string",
        "id" : "L1",
        "label" : "description",
        "modifiable" : true
      }
    } ],
    "HasHeadingLevel" : [ {
      "created_at" : "2023-10-03T14:31:17.365491+01:00",
      "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
      "statements" : { },
      "thing" : {
        "_class" : "literal",
        "created_at" : "2023-10-03T14:31:17.365491+01:00",
        "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
        "datatype" : "xsd:integer",
        "id" : "L1",
        "label" : "5",
        "modifiable" : true
      }
    } ],
    "P76020" : [ {
      "created_at" : "2023-10-03T14:31:17.365491+01:00",
      "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
      "statements" : { },
      "thing" : {
        "_class" : "literal",
        "created_at" : "2023-10-03T14:31:17.365491+01:00",
        "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
        "datatype" : "xsd:string",
        "id" : "L1",
        "label" : "5465463368674669679837",
        "modifiable" : true
      }
    } ],
    "P27" : [ {
      "created_at" : "2023-10-03T14:31:17.365491+01:00",
      "created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
      "statements" : { },
      "thing" : {
        "_class" : "resource",
        "classes" : [ "R28" ],
        "created_at" : "2023-10-06T11:28:14.613254+01:00",
        "created_by" : "00000000-0000-0000-0000-000000000000",
        "extraction_method" : "UNKNOWN",
        "featured" : false,
        "formatted_label" : null,
        "id" : "R1",
        "label" : "Default Label",
        "modifiable" : true,
        "observatory_id" : "00000000-0000-0000-0000-000000000000",
        "organization_id" : "00000000-0000-0000-0000-000000000000",
        "shared" : 0,
        "unlisted" : false,
        "verified" : false
      }
    } ]
  }
}

Listing template instances

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

Curl request

$ curl 'https://incubating.orkg.org/api/templates/R132/instances' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template-instance.v1+json'

The following list of request parameters are supported:

Request parameters

Parameter Description

q

A search term that must be contained in the label. (optional)

exact

Whether label matching is exact or fuzzy (optional, default: false)

visibility

Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional)

created_by

Filter for the UUID of the user or service who created this template instance. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned template instance can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned template instance can have. (optional)

observatory_id

Filter for the UUID of the observatory that the template instance belongs to. (optional)

organization_id

Filter for the UUID of the organization that the template instance belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/templates/R132/instances?q=label&exact=true&visibility=ALL_LISTED&created_by=f5a8d8a0-35a3-4d7b-b4a4-7d2363a61547&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=282a9649-a531-41cd-a0e6-948a83cf23ca&organization_id=4e171f0b-929b-4e8b-892c-fd29bf0f8e66' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template-instance.v1+json'

Editing a template instance

A PUT request updates an existing template instance with all the given parameters. The response will be 204 No Content when successful. The updated template instance (object) can be retrieved by following the URI in the Location header field.

Request fields

Path Type Description

statements

Object

Map of predicate ids to list of object ids that represent the statements of the template instance.

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.*

String

Key value pairs of literal temp ids to literal values. The type will be automatically assigned based on the template.

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.

classes

Object

Definition of classes that need to be created.

classes.*.label

String

The label of the class.

classes.*.uri

String

The uri of the class.

extraction_method

String

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

Curl request

$ curl 'https://incubating.orkg.org/api/templates/R123/instances/R456' -i -X PUT \
    -H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.template-instance.v1+json' \
    -d '{
  "classes" : {
    "#temp5" : {
      "label" : "class",
      "uri" : "https://orkg.org/class/C1"
    }
  },
  "extraction_method" : "MANUAL",
  "lists" : {
    "#temp4" : {
      "elements" : [ "#temp1", "C123" ],
      "label" : "list"
    }
  },
  "literals" : {
    "#temp2" : "0.1"
  },
  "predicates" : {
    "#temp3" : {
      "description" : "has result",
      "label" : "hasResult"
    }
  },
  "resources" : {
    "#temp1" : {
      "classes" : [ "Result" ],
      "label" : "MOTO"
    }
  },
  "statements" : {
    "P27" : [ "#temp1", "#temp2", "#temp3" ],
    "P24" : [ "#temp4", "#temp5", "R123" ]
  }
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R123/instances/R456

Rosetta Stone Templates

Rosetta Stone Templates represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They can be used to model the structure of statements following the rosetta stone approach. The provided endpoints aggregate these concepts into a rosetta stone template 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 rosetta stone template

A GET request provides information about a template.

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/templates/R21325' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-template.v1+json'

Response fields

Path Type Description

id

String

The identifier of the rosetta stone template.

label

String

The label of the rosetta stone template.

description

String

The description of the rosetta stone template.

formatted_label

String

The formatted label pattern of the rosetta stone template.

target_class

String

The target class of the rosetta stone template.

example_usage

String

One or more example sentences that demonstrate the usage of the statement that this template models.

properties

Array

The list of properties of the rosetta stone template. See template properties for more information.

organizations[]

Array

The list of IDs of the organizations the rosetta stone template belongs to.

observatories[]

Array

The list of IDs of the observatories the rosetta stone template belongs to.

created_at

OffsetDateTime

The timestamp when the rosetta stone template resource was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this rosetta stone template.

visibility

String

Visibility of the rosetta stone template. Can be one of "default", "featured", "unlisted" or "deleted".

unlisted_by

String

The UUID of the user or service who unlisted this rosetta stone template.

Listing rosetta stone templates

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

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/templates' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-template.v1+json'

The following list of request parameters are supported:

Request parameters

Parameter Description

q

Optional filter for the rosetta stone template label.

exact

Optional flag for whether label matching should be exact. (default: false)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Optional filter for the UUID of the user or service who created the rosetta stone template.

Creating rosetta stone templates

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

The first property of a rosetta stone template defines the subject position of the statement and is required to have a path of hasSubjectPosition, must have a minimum cardinality of at least one and is not a literal template property. All other properties define a object position, which must have a path of hasObjectPosition. At least one property is required to create a new rosetta stone template.

Request fields

Path Type Description

label

String

The label of the rosetta stone template.

description

String

The description of the rosetta stone template.

formatted_label

String

The formatted label pattern of the rosetta stone template.

example_usage

String

One or more example sentences that demonstrate the usage of the statement that this template models.

properties

Array

The list of properties of the rosetta stone template. The first property defines the subject position of the statement and is required to have a path of hasSubjectPosition, must have a minimum cardinality of at least one and is not a literal template property. All other properties define a object position, which must have a path of hasObjectPosition. At least one property is required to create a new rosetta stone template. See template properties for more information.

organizations[]

Array

The list of IDs of the organizations the rosetta stone template belongs to.

observatories[]

Array

The list of IDs of the observatories the rosetta stone template belongs to.

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/templates' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-template.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-template.v1+json' \
    -d '{
  "description" : "Some description about the Rosetta Stone Template",
  "example_usage" : "example sentence of the statement",
  "formatted_label" : "{P32}",
  "label" : "Dummy Rosetta Stone Template Label",
  "observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "properties" : [ {
    "description" : "property description",
    "label" : "property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "property placeholder"
  }, {
    "datatype" : "String",
    "description" : "string literal property description",
    "label" : "string literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "pattern" : "\\d+",
    "placeholder" : "string literal property placeholder"
  }, {
    "datatype" : "Integer",
    "description" : "number literal property description",
    "label" : "number literal property label",
    "max_count" : 2,
    "max_inclusive" : 10,
    "min_count" : 1,
    "min_inclusive" : 5,
    "path" : "P24",
    "placeholder" : "number literal property placeholder"
  }, {
    "datatype" : "C25",
    "description" : "literal property description",
    "label" : "literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "placeholder" : "literal property placeholder"
  }, {
    "class" : "C28",
    "description" : "resource property description",
    "label" : "resource property label",
    "max_count" : 4,
    "min_count" : 3,
    "path" : "P27",
    "placeholder" : "resource property placeholder"
  } ]
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/rosetta-stone/templates/R123

Rosetta Stone Statements

Rosetta stone statements are instances of rosetta stone templates and represent a semantically meaningful statement to a human reader.

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 rosetta stone statement

A GET request provides information about a rosetta stone statement or a specific rosetta stone statement version.

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements/R123' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'

Response fields

Path Type Description

id

String

The identifier of the rosetta stone statement.

context

String

The ID of the context resource of the rosetta stone statement, possibly indicating the origin of a statement. (optional)

template_id

String

The identifier of the template that was used to instantiate the rosetta stone statement.

class_id

String

The identifier of the class of the rosetta stone statement. This class is equivalent to the target class of the template used to instantiate the rosetta stone statement.

version_id

String

The ID of the backing version of the rosetta stone statement contents.

latest_version_id

String

The ID of the rosetta stone statement that always points to the latest version of this statement.

formatted_label

String

The formatted label at the time of creation of the template used to instantiate the rosetta stone statement.

subjects[]

Array

The ordered list of subject instance references used in the rosetta stone statement.

objects[]

Array

The ordered list of object position instances used in the rosetta stone statement.

objects[][]

Array

The ordered list of object instance references used for the object position index defined by the outer array.

created_at

OffsetDateTime

The timestamp when the rosetta stone statement was created. (Also see JavaDoc).

created_by

String

The UUID of the user or service who created this rosetta stone statement.

certainty

String

The certainty of the rosetta stone statement. Either of "LOW", "MODERATE", "HIGH".

negated

Boolean

Whether the statement represented by the rosetta stone statement instance is semantically negated.

organizations[]

Array

The list of IDs of the organizations the rosetta stone statement belongs to.

observatories[]

Array

The list of IDs of the observatories the rosetta stone statement belongs to.

extraction_method

String

The method used to extract the rosetta stone statement. Either of "AUTOMATIC", "MANUAL", "UNKNOWN".

visibility

String

Visibility of the rosetta stone statement. Can be one of "default", "featured", "unlisted" or "deleted".

unlisted_by

String

The UUID of the user or service who unlisted this rosetta stone statement.

modifiable

Boolean

Whether this rosetta stone statement can be modified.

deleted_at

OffsetDateTime

The timestamp when the rosetta stone statement was deleted. (Also see JavaDoc).

deleted_by

String

The UUID of the user or service who deleted this rosetta stone statement.

Listing rosetta stone statements

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

Only the most recent versions of rosetta stone statements will be returned.

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'

The following list of request parameters are supported:

Request parameters

Parameter Description

context

Filter for the id of the context that the rosetta stone statement was created with. (optional)

template_id

Filter for the template id that was used to instantiate the rosetta stone statement. (optional)

class_id

Filter for the class id of the rosetta stone statement. (optional)

visibility

Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED".

created_by

Filter for the UUID of the user or service who created the first version of the rosetta stone statement. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned rosetta stone statement can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned rosetta stone statement can have. (optional)

observatory_id

Filter for the UUID of the observatory that the rosetta stone statement belongs to. (optional)

organization_id

Filter for the UUID of the organization that the rosetta stone statement belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements?context=R123&template_id=R456&class_id=C123&visibility=ALL_LISTED&created_by=dca4080c-e23f-489d-b900-af8bfc2b0620&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'

Listing rosetta stone statement versions

A GET request returns a list of rosetta stone statement versions.

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements/R123/versions' -i -X GET \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'

Creating rosetta stone statements

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

Request fields

Path Type Description

template_id

String

The identifier of the templates that was used to instantiate the rosetta stone statement.

context

String

The ID of the context resource of the rosetta stone statement, possibly indicating the origin of a statement. (optional)

subjects[]

Array

The ordered list of subject instance IDs used in the rosetta stone statement.

objects[]

Array

The ordered list of object position instances used in the rosetta stone statement. The order of the objects corresponds to the order of the properties of the rosetta stone template.

objects[][]

Array

The ordered list of object instance IDs used for the object position index defined by the outer array.

certainty

String

The certainty of the rosetta stone statement. Either of "LOW", "MODERATE", "HIGH".

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.

classes

Object

Definition of classes that need to be created.

classes.*.label

String

The label of the class.

classes.*.uri

String

The uri of the class.

negated

Boolean

Whether the statement represented by the rosetta stone statement instance is semantically negated. (optional, default: false)

organizations[]

Array

The list of IDs of the organizations the rosetta stone statement belongs to.

observatories[]

Array

The list of IDs of the observatories the rosetta stone statement belongs to.

extraction_method

String

The method used to extract the rosetta stone statement. Either of "AUTOMATIC", "MANUAL", "UNKNOWN".

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json' \
    -d '{
  "certainty" : "HIGH",
  "classes" : {
    "#temp5" : {
      "label" : "class",
      "uri" : "https://orkg.org/class/C1"
    }
  },
  "context" : "R789",
  "extraction_method" : "MANUAL",
  "lists" : {
    "#temp4" : {
      "elements" : [ "#temp1", "C123" ],
      "label" : "list"
    }
  },
  "literals" : {
    "#temp2" : {
      "data_type" : "xsd:decimal",
      "label" : "0.1"
    }
  },
  "negated" : false,
  "objects" : [ [ "R987", "R654", "#temp2", "#temp3" ], [ "R321", "R741", "#temp4", "#temp5" ] ],
  "observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "predicates" : {
    "#temp3" : {
      "description" : "has result",
      "label" : "hasResult"
    }
  },
  "resources" : {
    "#temp1" : {
      "classes" : [ "Result" ],
      "label" : "MOTO"
    }
  },
  "subjects" : [ "R258", "R369", "#temp1" ],
  "template_id" : "R456"
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/rosetta-stone/statements/R123

Editing a rosetta stone statement

A POST request creates a new version of an existing rosetta stone statement with all the given parameters. The response will be 201 Created when successful. The revised rosetta stone statement (object) can be retrieved by following the URI in the Location header field.

Request fields

Path Type Description

subjects[]

Array

The ordered list of subject instance IDs used in the updated rosetta stone statement.

objects[]

Array

The ordered list of object position instances used in the updated rosetta stone statement. The order of the objects corresponds to the order of the properties of the rosetta stone template.

objects[][]

Array

The ordered list of object instance IDs used for the object position index defined by the outer array.

certainty

String

The certainty of the updated rosetta stone statement. Either of "LOW", "MODERATE", "HIGH".

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.

classes

Object

Definition of classes that need to be created.

classes.*.label

String

The label of the class.

classes.*.uri

String

The uri of the class.

negated

Boolean

Whether the statement represented by the updated rosetta stone statement instance is semantically negated. (optional, default: false)

organizations[]

Array

The list of IDs of the organizations the rosetta stone statement belongs to.

observatories[]

Array

The list of IDs of the observatories the rosetta stone statement belongs to.

extraction_method

String

The method used to extract the updated rosetta stone statement. Either of "AUTOMATIC", "MANUAL", "UNKNOWN".

Curl request

$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements/R123' -i -X POST \
    -H 'Content-Type: application/vnd.orkg.rosetta-stone-statement.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json' \
    -d '{
  "certainty" : "HIGH",
  "classes" : {
    "#temp5" : {
      "label" : "class",
      "uri" : "https://orkg.org/class/C1"
    }
  },
  "extraction_method" : "MANUAL",
  "lists" : {
    "#temp4" : {
      "elements" : [ "#temp1", "C123" ],
      "label" : "list"
    }
  },
  "literals" : {
    "#temp2" : {
      "data_type" : "xsd:decimal",
      "label" : "0.1"
    }
  },
  "negated" : false,
  "objects" : [ [ "R987", "R654", "#temp2", "#temp3" ], [ "R321", "R741", "#temp4", "#temp5" ] ],
  "observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "predicates" : {
    "#temp3" : {
      "description" : "has result",
      "label" : "hasResult"
    }
  },
  "resources" : {
    "#temp1" : {
      "classes" : [ "Result" ],
      "label" : "MOTO"
    }
  },
  "subjects" : [ "R258", "R369", "#temp1" ]
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/rosetta-stone/statements/R124

Deleting a rosetta stone statement

Soft-deleting a rosetta stone statement

A DELETE request soft-deletes a rosetta stone statement with all its versions. The response will be 204 No Content when successful.

Curl request
$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements/R123' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'
Path parameters
Table 2. /api/rosetta-stone/statements/{id}
Parameter Description

id

The id of the rosetta stone statement to soft-delete.

HTTP response
HTTP/1.1 204 No Content

Fully deleting a rosetta stone statement

A DELETE request fully deletes a rosetta stone statement with all its versions. The response will be 204 No Content when successful.

The user performing the action needs to be a curator.
Curl request
$ curl 'https://incubating.orkg.org/api/rosetta-stone/statements/R123/versions' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/vnd.orkg.rosetta-stone-statement.v1+json'
Path parameters
Table 2. /api/rosetta-stone/statements/{id}/versions
Parameter Description

id

The id of the rosetta stone statement to delete.

HTTP response
HTTP/1.1 204 No Content

Content-Types

Content-Types represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints allow to operate across multiple concepts.

Listing Content-Types

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

Whenever possible, individual content-type endpoints should be used, to optimize performance.

Curl request

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

The following list of request parameters are supported:

Request parameters

Parameter Description

classes

Filter for the content type classes. Either of "PAPER","COMPARISON","VISUALIZATION","TEMPLATE","LITERATURE_LIST","SMART_REVIEW" (optional)

visibility

Filter for visibility. Either of "ALL_LISTED","UNLISTED","FEATURED","NON_FEATURED","DELETED". (optional)

created_by

Filter for the UUID of the user or service who created this content type. (optional)

created_at_start

Filter for the created at timestamp, marking the oldest timestamp a returned content type can have. (optional)

created_at_end

Filter for the created at timestamp, marking the most recent timestamp a returned content type can have. (optional)

observatory_id

Filter for the UUID of the observatory that the content type belongs to. (optional)

organization_id

Filter for the UUID of the organization that the content type belongs to. (optional)

research_field

Filter for research field id that the content type belongs to. (optional)

include_subfields

Flag for whether subfields are included in the search or not. (optional, default: false)

sdg

Filter for the sustainable development goal that the content type belongs to. (optional)

Curation

Curation endpoints provide specialised views for entities of the graph.

Listing predicates without descriptions

A GET request lists all predicates without descriptions:

Curl request

$ curl 'https://incubating.orkg.org/api/curation/predicates-without-descriptions' -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: 536

{
  "content" : [ {
    "_class" : "predicate",
    "created_at" : "2023-10-04T13:30:16.931457+01:00",
    "created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
    "description" : null,
    "id" : "P1",
    "label" : "some predicate label",
    "modifiable" : true
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : "INSTANCE",
  "size" : 1,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}

Listing classes without descriptions

A GET request lists all classes without descriptions:

Curl request

$ curl 'https://incubating.orkg.org/api/curation/classes-without-descriptions' -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: 561

{
  "content" : [ {
    "_class" : "class",
    "created_at" : "2023-10-05T12:29:15.3155145+01:00",
    "created_by" : "dc8b2055-c14a-4e9f-9fcd-e0b79cf1f834",
    "description" : null,
    "id" : "OK",
    "label" : "some label",
    "modifiable" : true,
    "uri" : "https://example.org/OK"
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : "INSTANCE",
  "size" : 1,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}

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.

An RDF format media type can be provided via the Accept header field. For a list of supported media types, see Supported media types below.

Resolve a resource

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

$ curl 'https://incubating.orkg.org/api/vocab/resource/R1' -i -X GET \
    -H 'Accept: application/rdf+xml'
HTTP/1.1 200 OK
Content-Type: application/rdf+xml;charset=UTF-8
Content-Length: 535

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:r="http://orkg.org/orkg/resource/" xmlns:p="http://orkg.org/orkg/predicate/" xmlns:c="http://orkg.org/orkg/class/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">

    <rdf:Description rdf:about="http://orkg.org/orkg/resource/R1">

        <rdfs:label>Default Label</rdfs:label>

        <rdf:type rdf:resource="http://orkg.org/orkg/class/Resource"/>

    </rdf:Description>

</rdf:RDF>

Resolve a predicate

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

$ curl 'https://incubating.orkg.org/api/vocab/predicate/P1' -i -X GET \
    -H 'Accept: text/n3'
HTTP/1.1 200 OK
Content-Type: text/n3;charset=UTF-8
Content-Length: 266

@prefix p: <http://orkg.org/orkg/predicate/> .
@prefix c: <http://orkg.org/orkg/class/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

p:P1 a c:Predicate;
  rdfs:label "some predicate label" .

Resolve a class

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

$ curl 'https://incubating.orkg.org/api/vocab/class/C1' -i -X GET \
    -H 'Accept: application/trig'
HTTP/1.1 200 OK
Content-Type: application/trig;charset=UTF-8
Content-Length: 313

@prefix c: <http://orkg.org/orkg/class/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .

{
  c:C1 a owl:Class;
    rdfs:label "some label";
    owl:equivalentClass "https://example.org/OK" .
}

Supported media types

Serialization to the following RDF media types is supported:

Table 2. Supported RDF media types
Media Type 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

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/78659e1b-f4fd-4946-a664-5a3d01ebcc59' -i -X GET \
    -H 'Content-Type: application/json;charset=utf-8' \
    -H 'Accept: application/json'

HTTP response

HTTP/1.1 200 OK
Cache-Control: max-age=300
Content-Type: application/json
Content-Length: 395

{
  "display_name" : "Some User",
  "id" : "78659e1b-f4fd-4946-a664-5a3d01ebcc59",
  "joined_at" : "2024-07-19T13:59:03.068817916Z",
  "observatory_id" : "00000000-0000-0000-0000-000000000000",
  "organization_id" : "00000000-0000-0000-0000-000000000000",
  "avatar_url" : "https://www.gravatar.com/avatar/9ab3be8f21fe883eeb99423a16618a34",
  "gravatar_id" : "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

[ {
  "created_by" : "60d4a5b4-5ca8-4fe6-82cd-577af23c949d",
  "display_id" : "test_organization",
  "homepage" : "https://www.example.org",
  "id" : "fab4e690-6682-4b2d-b887-6c2eb0fa37a8",
  "name" : "Test Organization",
  "observatory_ids" : [ ],
  "type" : "GENERAL"
} ]

Fetching an organization

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/organizations/7d6288cb-850d-4be7-9fb5-aaee433298a2' -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

{
  "created_by" : "fb1d219b-d9c7-4df7-b5e2-0928749848f9",
  "display_id" : "test_organization",
  "homepage" : "https://www.example.org",
  "id" : "7d6288cb-850d-4be7-9fb5-aaee433298a2",
  "name" : "Test Organization",
  "observatory_ids" : [ ],
  "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: 828

{
  "content" : [ {
    "description" : "Example description",
    "display_id" : "test_observatory",
    "id" : "1a5f6fa5-c863-4141-b195-4b86e1ddfedb",
    "members" : [ ],
    "name" : "Test Observatory",
    "organization_ids" : [ "999fa772-db68-433b-8ddb-1af23a8fbaf2" ],
    "research_field" : {
      "id" : "R5",
      "label" : "label"
    },
    "sdgs" : [ ]
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : {
    "offset" : 0,
    "pageNumber" : 0,
    "pageSize" : 20,
    "paged" : true,
    "sort" : {
      "empty" : true,
      "sorted" : false,
      "unsorted" : true
    },
    "unpaged" : false
  },
  "size" : 20,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}

Creating observatories

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

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

Request fields

Path Type Description

name

String

The name of the observatory. Alternatively, the legacy field observatory_name can be used for equivalent behavior.

organization_id

String

The id of the organization that the observatory belongs to.

description

String

The description of the observatory.

research_field

String

The id of the research field of the observatory.

display_id

String

The URI slug of the observatory.

sdgs

Array

The set of ids of sustainable development goals the observatory belongs to.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "description" : "Example Description",
  "display_id" : "test_observatory",
  "name" : "Test Observatory",
  "organization_id" : "a700c55f-aae2-4696-b7d5-6e8b89f66a8f",
  "research_field" : "R1234",
  "sdgs" : [ "SDG1" ]
}'

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33
Content-Type: application/json
Content-Length: 347

{
  "description" : "Example Description",
  "display_id" : "test_observatory",
  "id" : "95565e51-2b80-4c28-918c-6fbc5e2a9b33",
  "members" : [ ],
  "name" : "Test Observatory",
  "organization_ids" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "research_field" : {
    "id" : "R1234",
    "label" : "Default Label"
  },
  "sdgs" : [ "SDG1" ]
}

Fetching an observatory

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/observatories/58622c37-74ed-41ac-8241-31b05e2abfaa' -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: 329

{
  "description" : "Example description",
  "display_id" : "test_observatory",
  "id" : "58622c37-74ed-41ac-8241-31b05e2abfaa",
  "members" : [ ],
  "name" : "Test Observatory",
  "organization_ids" : [ "8b618761-a09a-438f-9091-aeec7078869b" ],
  "research_field" : {
    "id" : "R4",
    "label" : "label"
  },
  "sdgs" : [ ]
}

Editing an observatory

A PATCH request updates an existing observatory with the given parameters. Only fields provided in the response, and therefore non-null, will be updated. The response will be 204 No Content when successful. The updated observatory (object) can be retrieved by following the URI in the Location header field.

This endpoint can only be accessed by curators.

Request fields

Path Type Description

name

String

The new name of the observatory. (optional)

organizations

Array

The new set of organizations that the observatory belongs to. (optional)

description

String

The new description of the observatory. (optional)

research_field

String

The id of the new research field of the observatory. (optional)

sdgs

Array

The new set of ids of sustainable development goals that the observatory belongs to. (optional)

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/73b2e081-9b50-4d55-b464-22d94e8a25f6' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "description" : "new observatory description",
  "name" : "updated",
  "organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
  "research_field" : "R123",
  "sdgs" : [ "SDG1" ]
}'

HTTP response

HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/observatories/73b2e081-9b50-4d55-b464-22d94e8a25f6

Listing papers of an observatory

A GET request returns a paged list of paper resources.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/2a4f9963-64b9-45af-b1e8-e38f0807d19b/papers?visibility=FEATURED&filter_config=%5B%7B%22exact%22%3Atrue%2C%22path%22%3A%5B%7B%22value%22%3A%22P105027%22%7D%5D%2C%22range%22%3A%7B%22value%22%3A%22String%22%7D%2C%22values%22%3A%5B%7B%22op%22%3A%22EQ%22%2C%22value%22%3A%22yes%22%7D%5D%7D%2C%7B%22exact%22%3Afalse%2C%22path%22%3A%5B%7B%22value%22%3A%22P32%22%7D%5D%2C%22range%22%3A%7B%22value%22%3A%22Resources%22%7D%2C%22values%22%3A%5B%7B%22op%22%3A%22EQ%22%2C%22value%22%3A%22R1234%22%7D%5D%7D%5D' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Request parameters

Parameter Description

filter_config

The filter config to use. (optional)

visibility

Visibility of this resource. Can be one of "listed", "featured", "unlisted" or "deleted". (optional)

This call features filter configs, check the chapter Filter Configs for more information on filter configs.
Sorting is supported for the following fields: id, created_by, created_at. It is also possible to sort by the matched value of each search filter. To sort by the first search filter, the parameter value0 can be used. If a second search filter is defined, the parameter value1 can be used. By default, elements are sorted by created_at (descending).

Observatory Filters

Observatory filters are persistent filter configurations (presets) for observatories.

Fetching an Observatory Filter

A GET request provides information about an observatory filter, which always belongs to a specific observatory.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Path parameters

Table 3. /api/observatories/{observatoryId}/filters/{filterId}
Parameter Description

observatoryId

The identifier of the observatory that the filter belongs to.

filterId

The identifier of the filter to retrieve.

Response fields

Path Type Description

id

String

The identifier of the filter.

observatory_id

String

The id of the observatory that the filter belongs to.

label

String

The label of the filter.

path[]

Array

Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement.

range

String

The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching.

exact

Boolean

Whether to exactly match the given path. If true, the given path needs to exactly match, starting from the contribution resource. If false, the given path needs to exactly match, starting at any node in the subgraph of the contribution or the contribution node itself. The total path length limited to 10, including the length of the specified path, starting from the contribution node.

created_at

OffsetDateTime

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

created_by

String

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

featured

Boolean

Whether the filter is featured or not.

Listing Observatory Filters

A GET request returns a paged list of observatory filters that belong to the specified observatory. If no paging request parameters are provided, the default values will be used.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Path parameters

Table 3. /api/observatories/{observatoryId}/filters
Parameter Description

observatoryId

The identifier of the observatory that the filters belongs to.

Creating Observatory Filters

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

The user performing the action needs to be a curator or a member of the observatory.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "filter",
  "path" : [ "P32" ],
  "range" : "Resources",
  "exact" : false,
  "featured" : false
}'

Path parameters

Table 3. /api/observatories/{observatoryId}/filters
Parameter Description

observatoryId

The identifier of the observatory that the filters belongs to.

Request fields

Path Type Description

label

String

The label of the filter.

path[]

Array

Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement.

range

String

The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching.

exact

Boolean

Whether to exactly match the given path. If true, the given path needs to exactly match, starting from the contribution resource. If false, the given path needs to exactly match, starting at any node in the subgraph of the contribution or the contribution node itself. The total path length limited to 10, including the length of the specified path, starting from the contribution node.

featured

Boolean

Whether or not the filter is featured. (optional)

HTTP response

HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831

Updating Observatory Filters

A PATCH request updates an existing observatory filter with the given parameters. The response will be 204 No Content when successful.

The user performing the action needs to be a curator or a member of the observatory.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831' -i -X PATCH \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
  "label" : "filter",
  "path" : [ "P32" ],
  "range" : "Resources",
  "exact" : false,
  "featured" : false
}'

Path parameters

Table 3. /api/observatories/{observatoryId}/filters/{filterId}
Parameter Description

observatoryId

The identifier of the observatory that the filters belongs to.

filterId

The identifier of the filter to update.

Request fields

Path Type Description

label

String

The new label of the filter. (optional)

path[]

Array

Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. (optional)

range

String

The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching. (optional)

exact

Boolean

Whether to exactly match the given path. If true, the given path needs to exactly match, starting from the contribution resource. If false, the given path needs to exactly match, starting at any node in the subgraph of the contribution or the contribution node itself. The total path length limited to 10, including the length of the specified path, starting from the contribution node.(optional)

featured

Boolean

Whether or not the filter is featured. (optional)

HTTP response

HTTP/1.1 204 No Content

Deleting Observatory Filters

A DELETE request deletes an observatory filter. The response will be 204 No Content when successful.

The user performing the action needs to be a curator or a member of the observatory.

Curl request

$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Path parameters

Table 3. /api/observatories/{observatoryId}/filters/{filterId}
Parameter Description

observatoryId

The identifier of the observatory that the filters belongs to.

filterId

The identifier of the filter to delete.

HTTP response

HTTP/1.1 204 No Content

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/R254/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: 453

[ {
  "contributions" : 1,
  "user" : {
    "display_name" : "test_user",
    "id" : "886c4229-f84c-4053-ba22-bd128207af3b",
    "joined_at" : "2024-07-19T14:00:20.740366736Z",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "avatar_url" : "https://www.gravatar.com/avatar/909c3113e76a1d52913c88135fbb431e",
    "gravatar_id" : "909c3113e76a1d52913c88135fbb431e"
  }
} ]

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.

All GET requests share the same path parameter, listed below, and support visibility filtering. The responses are paged.

Path parameters

Table 3. /api/research-fields/{id}
Parameter Description

id

The ID of the research field.

In the following sections, the response fields of the page object are omitted for brevity.

Research fields and content types

Fetching content types of a research field

A GET request for a given research field returns a paged list of content type resources that belong to this research field. Certain subsets of content types are obtained via the classes parameter. The endpoint supports Visibility filtering (obsolete).

Path parameters
Table 4. /api/research-fields/{id}
Parameter Description

id

The ID of the research field.

Request parameters
Parameter Description

classes

A list of classes to filter against. The classes must support research fields. Must be one of Comparison, LiteratureListPublished, Paper, Problem, SmartReviewPublished, Visualization.

featured

Return only featured results. Defaults to false. (Deprecated. See Visibility filter.)

unlisted

Return only unlisted results. Defaults to false. (Deprecated. See Visibility filter.)

visibility

The visibility modifier. Must be one of ALL_LISTED, UNLISTED, FEATURED, NON_FEATURED, DELETED. If it is not provided, it will be determined from the featured and unlisted request parameters (where available).

Response fields
Path Type Description

content

Array

A (sorted) array of content type resources.

Fetching content types of a research field and its subfields

A GET request to /api/research-fields/{id}/subfields returns a paged list of content type resources belonging to a given research field and its subfields. All path, request and response parameters are exactly the same as on the endpoint without subfields.

Research fields and research problems

Listing research problems of a research field

A GET request to /api/research-fields/{id}/problems lists all research problems used within all papers under the specified research field, along with their paper count. The endpoint supports Visibility filtering (obsolete).

Response fields
Path Type Description

content

Array

A (sorted) array of problems and paper counts (see below).

The response objects have the following form:

Path Type Description

problem

Object

A research problem resource, i. e. a resource of class Problem.

papers

Number

The number of papers that address this research problem.

Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/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: 892

{
  "content" : [ {
    "papers" : 5,
    "problem" : {
      "_class" : "resource",
      "classes" : [ "Problem" ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "RP234",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : "INSTANCE",
  "size" : 1,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}

Listing Problems in field including sub research fields

A GET request to /api/research-fields/{id}/subfields/research-problems returns a paged list of research problem resources belonging to a given research field and its subfields. All path and request parameters are exactly the same as on the endpoint without subfields.

Research fields and papers

Listing Papers of a research field

A GET request to /api/research-fields/{id}/papers returns a paged list of paper resources belonging to a given research field.

Response fields
Path Type Description

content

Array

A (sorted) array of paper resources.

Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/papers' -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: 1373

{
  "content" : [ {
    "_class" : "resource",
    "classes" : [ "Paper" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "P1",
    "label" : "Some interesting title",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 12,
    "unlisted" : false,
    "verified" : false
  }, {
    "_class" : "resource",
    "classes" : [ "Paper" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "P2",
    "label" : "Even more interesting title",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 13,
    "unlisted" : false,
    "verified" : false
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : "INSTANCE",
  "size" : 2,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

Listing Papers of a research field and its subfields

A GET request to /api/research-fields/{id}/subfields/papers returns a paged list of paper resources belonging to a given research field and its subfields. All path and request parameters are exactly the same as on the endpoint without subfields.

Research fields and contributors

Listing Contributors of a research field

A GET request to /api/research-fields/{id}/contributors returns a paged list of contributors that contributed to a given research field.

This endpoint does not support visibility filtering! The only supported path parameter is featured.
Response fields
Path Type Description

content

Array

A (sorted) array of contributors.

Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/contributors' -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: 1021

{
  "content" : [ {
    "display_name" : "Some One",
    "id" : "3a6b2e25-5890-44cd-b6e7-16137f8b9c6a",
    "joined_at" : "2023-10-06T10:37:17.055493+01:00",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "avatar_url" : "https://www.gravatar.com/avatar/?d=mp&f=y",
    "gravatar_id" : "?d=mp&f=y"
  }, {
    "display_name" : "Another One",
    "id" : "fd4a1478-ce49-4e8e-b04a-39a8cac9e33f",
    "joined_at" : "2023-10-06T10:37:17.055493+01:00",
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "avatar_url" : "https://www.gravatar.com/avatar/?d=mp&f=y",
    "gravatar_id" : "?d=mp&f=y"
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : "INSTANCE",
  "size" : 2,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

Listing Contributors of a research field and its subfields

A GET request to /api/research-fields/{id}/subfields/contributors returns a paged list of contributors that contributed to a given research field and its subfields. All path and request parameters are exactly the same as on the endpoint without subfields.

Research fields and comparisons

Listing comparisons of a research field

A GET request to /api/research-fields/{id}/comparisons returns a paged list of comparison resources belonging to a given research field.

Response fields
Path Type Description

content

Array

A (sorted) array of comparison resources.

Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/comparisons' -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: 1360

{
  "content" : [ {
    "_class" : "resource",
    "classes" : [ "Comparison" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "P1",
    "label" : "Default Label",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 12,
    "unlisted" : false,
    "verified" : false
  }, {
    "_class" : "resource",
    "classes" : [ "Comparison" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "P2",
    "label" : "Default Label",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 13,
    "unlisted" : false,
    "verified" : false
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 2,
  "pageable" : "INSTANCE",
  "size" : 2,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 2,
  "totalPages" : 1
}

Listing comparisons of a research field and its subfields

A GET request to /api/research-fields/{id}/subfields/comparisons returns a paged list of comparison resources belonging to a given research field and its subfields. All path and request parameters are exactly the same as on the endpoint without subfields.

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: 907

{
  "content" : [ {
    "child_count" : 1,
    "resource" : {
      "_class" : "resource",
      "classes" : [ "ResearchField" ],
      "created_at" : "2023-10-06T11:28:14.613254+01:00",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "subfield",
      "label" : "Default Label",
      "modifiable" : true,
      "observatory_id" : "00000000-0000-0000-0000-000000000000",
      "organization_id" : "00000000-0000-0000-0000-000000000000",
      "shared" : 0,
      "unlisted" : false,
      "verified" : false
    }
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : "INSTANCE",
  "size" : 1,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}
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: 827

{
  "content" : [ {
    "_class" : "resource",
    "classes" : [ "ResearchField" ],
    "created_at" : "2023-10-06T11:28:14.613254+01:00",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "parent",
    "label" : "Default Label",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 0,
    "unlisted" : false,
    "verified" : false
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 0,
  "numberOfElements" : 1,
  "pageable" : "INSTANCE",
  "size" : 1,
  "sort" : {
    "empty" : true,
    "sorted" : false,
    "unsorted" : true
  },
  "totalElements" : 1,
  "totalPages" : 1
}

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: 825

{
  "content" : [ {
    "_class" :