Overview

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

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

HTTP verbs

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

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

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

HTTP status codes

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

Status code Usage

200 OK

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

201 Created

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

204 No Content

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

400 Bad Request

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

404 Not Found

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

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

Authentication (AuthN)

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

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

Obtaining an access token

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

grant_type

Always password.

username

The email address of the user.

password

The password defined by the user.

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

Example:

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

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

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

Using the token

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

Example:

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

Obtaining user information

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

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

Changing user information

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

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

Changing the password

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

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

Registering a user

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

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

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

Statements

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

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

Predicates represent edges (relationships) in the graph.

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

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

Listing statements

A GET request lists all the statements:

Curl request

$ curl '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" : "R248",
  "predicate_id" : "P16",
  "object_id" : "R249"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/statements/
Content-Type: application/json
Content-Length: 1464

{
  "created_at" : "2024-03-28T15:50:52.307274587Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "id" : "S470",
  "modifiable" : true,
  "object" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-03-28T15:50:52.145895722Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R249",
    "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-03-28T15:50:52.14917043Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P16",
    "label" : "less than",
    "modifiable" : true
  },
  "subject" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-03-28T15:50:52.141863933Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R248",
    "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/S474' -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-03-28T15:50:52.888721901Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "id" : "S474",
  "modifiable" : true,
  "object" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-03-28T15:50:52.702836784Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R255",
    "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-03-28T15:50:52.860542181Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P19",
    "label" : "blah",
    "modifiable" : true
  },
  "subject" : {
    "_class" : "resource",
    "classes" : [ ],
    "created_at" : "2024-03-28T15:50:52.698837805Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R254",
    "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/R250/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: 4718

{
  "root" : "R250",
  "statements" : [ {
    "created_at" : "2024-03-28T15:50:52.553425194Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S473",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.488885066Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R253",
      "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-03-28T15:50:52.496765903Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P17",
      "label" : "blah",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.466271954Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R251",
      "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-03-28T15:50:52.540686428Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S472",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.474844831Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R252",
      "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-03-28T15:50:52.50705142Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P18",
      "label" : "blub",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.461867095Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R250",
      "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-03-28T15:50:52.525185694Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "id" : "S471",
    "modifiable" : true,
    "object" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.466271954Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R251",
      "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-03-28T15:50:52.496765903Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "description" : null,
      "id" : "P17",
      "label" : "blah",
      "modifiable" : true
    },
    "subject" : {
      "_class" : "resource",
      "classes" : [ ],
      "created_at" : "2024-03-28T15:50:52.461867095Z",
      "created_by" : "00000000-0000-0000-0000-000000000000",
      "extraction_method" : "UNKNOWN",
      "featured" : false,
      "formatted_label" : null,
      "id" : "R250",
      "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: 1004

{
  "content" : [ {
    "_class" : "class",
    "created_at" : "2024-03-28T15:50:39.4642424Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C5",
    "label" : "research contribution",
    "modifiable" : true,
    "uri" : null
  }, {
    "_class" : "class",
    "created_at" : "2024-03-28T15:50:39.474004756Z",
    "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-03-28T15:50:39.369049862Z",
  "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-03-28T15:50:38.490756508Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C2",
    "label" : "research topic",
    "modifiable" : true,
    "uri" : null
  }, {
    "_class" : "class",
    "created_at" : "2024-03-28T15:50:38.481696831Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "C0",
    "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
}

Lookup resources by class

List all resources that are of the provided class type

Curl request

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

HTTP response

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

{
  "content" : [ {
    "_class" : "resource",
    "classes" : [ "C10" ],
    "created_at" : "2024-03-28T15:50:39.940920839Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R244",
    "label" : "Contribution 1",
    "modifiable" : true,
    "observatory_id" : "00000000-0000-0000-0000-000000000000",
    "organization_id" : "00000000-0000-0000-0000-000000000000",
    "shared" : 0,
    "unlisted" : false,
    "verified" : false
  }, {
    "_class" : "resource",
    "classes" : [ "C10" ],
    "created_at" : "2024-03-28T15:50:40.147506209Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "extraction_method" : "UNKNOWN",
    "featured" : false,
    "formatted_label" : null,
    "id" : "R245",
    "label" : "Contribution 2",
    "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" : 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"
}

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 two distinct sets 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)

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&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'

Request parameters

Parameter Description

q

The fuzzy search string for the label of the resource.

base_class

The id of the base class that every resource has to be an instance of.

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

{
  "_class" : "resource",
  "classes" : [ ],
  "created_at" : "2024-03-28T15:50:49.78068061Z",
  "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 if available

Editing a resource

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

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-03-28T15:50:49.888588293Z",
  "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-03-28T15:50:50.176223786Z",
  "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: 188

{
  "error" : "Not Found",
  "message" : "Resource \"NONEXISTENT\" not found.",
  "path" : "/api/resources/NONEXISTENT",
  "status" : 404,
  "timestamp" : "2024-03-28T15:50:50.31241628Z"
}

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/R2' -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 \"R2\" because it is used in at least one statement.",
  "path" : "/api/resources/R2",
  "status" : 403,
  "timestamp" : "2024-03-28T15:50:49.361167241Z"
}

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-03-28T15:50:41.516128278Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P10",
    "label" : "knows",
    "modifiable" : true
  }, {
    "_class" : "predicate",
    "created_at" : "2024-03-28T15:50:41.512429369Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P9",
    "label" : "has name",
    "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-03-28T15:50:41.180891521Z",
  "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-03-28T15:50:41.475744161Z",
  "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: 956

{
  "content" : [ {
    "_class" : "predicate",
    "created_at" : "2024-03-28T15:50:41.002144931Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "description" : null,
    "id" : "P4",
    "label" : "has name",
    "modifiable" : true
  }, {
    "_class" : "predicate",
    "created_at" : "2024-03-28T15:50:41.00589546Z",
    "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
}

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

{
  "_class" : "literal",
  "created_at" : "2024-03-28T15:50:40.656448777Z",
  "created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
  "datatype" : "xs:foo",
  "id" : "L164",
  "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/L165' -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-03-28T15:50:40.725236474Z",
  "created_by" : "00000000-0000-0000-0000-000000000000",
  "datatype" : "dt:new",
  "id" : "L165",
  "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-03-28T15:50:40.504812969Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "datatype" : "xsd:string",
    "id" : "L163",
    "label" : "research topic",
    "modifiable" : true
  }, {
    "_class" : "literal",
    "created_at" : "2024-03-28T15:50:40.496791941Z",
    "created_by" : "00000000-0000-0000-0000-000000000000",
    "datatype" : "xsd:string",
    "id" : "L161",
    "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.

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

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.

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

Snippet request-parameters not found for operation::comparisons-get-paged

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

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 1. /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 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 1. /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

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.

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.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[].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[].id

String

The id of the linked resource.

sections[].entries[].label

String

The label of the linked resource.

sections[].entries[].classes

Array

The classes of the linked resource.

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.

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=c0afb083-1e54-461c-82e3-9641ef795ed7&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=ea49466b-726f-46c5-878f-c09be20fc0b8&organization_id=b72212d0-d457-4d55-ba2e-a53010cc6e19&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'

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.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[].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[].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[].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[].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.description

String

The description of the linked predicate.

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[].description

String

The description of the entity, if the entity is a predicate.

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[].description

String

The description of the predicate.

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.

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=1cea89c6-d80b-4e39-b771-5541db028631&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=0cd69d1a-7277-4bff-bdde-036f6cb28e09&organization_id=e8c0e29e-08f4-4ae8-ae6c-ca0f08cc37c4&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'

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.

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 properties of the template.

properties[].id

String

The id of the property.

properties[].label

String

The label of the property.

properties[].placeholder

String

The placeholder of the property.

properties[].description

String

The description of the property.

properties[].order

Number

The order of the property.

properties[].min_count

Number

The minimum cardinality of the property.

properties[].max_count

Number

The maximum cardinality of the property.

properties[].pattern

String

The pattern (regex) of the property.

properties[].path

Object

The predicate path of the property.

properties[].path.id

String

The id of the predicate.

properties[].path.label

String

The label of the predicate.

properties[].datatype

Object

The data type of the property, if the property is a literal property.

properties[].created_at

OffsetDateTime

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

properties[].created_by

String

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

properties[].datatype.id

String

The id of the data type.

properties[].datatype.label

String

The label of the data type.

properties[].class

Object

The class range of the property, if the property is a literal property.

properties[].class.id

String

The id of the class.

properties[].class.label

String

The label of the class.

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.

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 property descriptions of the template. They can either be literal properties or resource properties. This is denoted by the class (resource) and datatype (literal) properties.

properties[].label

String

The label of the property.

properties[].placeholder

String

The placeholder of the property. (optional)

properties[].description

String

The description of the property. (optional)

properties[].min_count

Number

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

properties[].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)

properties[].pattern

String

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

properties[].path

String

The predicate id for the path of the property.

properties[].class

String

The class id of the range of the property, indicating a resource property. Mutually exclusive with datatype.

properties[].datatype

String

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

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" : [ {
    "datatype" : "C25",
    "description" : "literal property description",
    "label" : "literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "pattern" : "\\d+",
    "placeholder" : "literal property placeholder"
  }, {
    "class" : "C28",
    "description" : "resource property description",
    "label" : "resource property label",
    "max_count" : 4,
    "min_count" : 3,
    "path" : "P27",
    "pattern" : "\\w+",
    "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 property descriptions of the template. They can either be literal properties or resource properties. This is denoted by the class (resource) and datatype (literal) properties. (optional)

properties[].label

String

The label of the property.

properties[].placeholder

String

The placeholder of the property. (optional)

properties[].description

String

The description of the property. (optional)

properties[].min_count

Number

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

properties[].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)

properties[].pattern

String

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

properties[].path

String

The predicate id for the path of the property.

properties[].class

String

The class id of the range of the property, indicating a resource property. Mutually exclusive with datatype.

properties[].datatype

String

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

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" : [ {
    "datatype" : "C25",
    "description" : "literal property description",
    "label" : "literal property label",
    "max_count" : 2,
    "min_count" : 1,
    "path" : "P24",
    "pattern" : "\\d+",
    "placeholder" : "literal property placeholder"
  }, {
    "class" : "C28",
    "description" : "resource property description",
    "label" : "resource property label",
    "max_count" : 4,
    "min_count" : 3,
    "path" : "P27",
    "pattern" : "\\w+",
    "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

Creating template properties

A POST request creates a new template property with all the given parameters. 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)

pattern

String

The pattern (regular expression) of the property. (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. Mutually exclusive with datatype.

datatype

String

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

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",
  "pattern" : "\\d+",
  "placeholder" : "literal property placeholder"
}'

HTTP response

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

Editing a template property

A PUT request updates an existing template property with all the given parameters. 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.

pattern

String

The pattern (regular expression) of the property.

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. Mutually exclusive with datatype.

datatype

String

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

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",
  "pattern" : "\\d+",
  "placeholder" : "literal 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: 1824

{
  "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" : "Default Label",
        "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=3599de15-5268-4f20-bad5-90f49ec549d9&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=ae9b200d-47d5-4488-ae5e-e2856f6248da&organization_id=07eed0a2-ab1b-462f-ba61-4b66cce534d9' -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

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 1. 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/acc6cd06-68f5-4c63-a906-2b13d1f9fb02' -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" : "acc6cd06-68f5-4c63-a906-2b13d1f9fb02",
  "joined_at" : "2024-03-28T15:49:17.951610621Z",
  "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" : "473af6d6-c0f3-4cc9-8012-64b2e668ba35",
  "display_id" : "test_organization",
  "homepage" : "https://www.example.org",
  "id" : "d8743d71-73fd-4cfa-bd8a-1f7503e511cf",
  "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/c5197bce-5644-4f47-9a1f-87c162cfe2c7' -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" : "306d4410-d99e-4620-8acf-a2e5018b44f0",
  "display_id" : "test_organization",
  "homepage" : "https://www.example.org",
  "id" : "c5197bce-5644-4f47-9a1f-87c162cfe2c7",
  "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" : "f1511c21-245e-4364-a4a2-4ed6809c3def",
    "members" : [ ],
    "name" : "Test Observatory",
    "organization_ids" : [ "212e66e8-ceb1-47e6-8ac5-8cbf0d02710f" ],
    "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/b2be546c-30a2-45d0-99ce-f6b0f2949d18' -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" : "b2be546c-30a2-45d0-99ce-f6b0f2949d18",
  "members" : [ ],
  "name" : "Test Observatory",
  "organization_ids" : [ "80dc9ec1-91fb-4f14-9e2e-de8eacdc4adb" ],
  "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/deaab9d4-4c5a-4062-b3b7-1058eaacf352/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 2. /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 2. /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 2. /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/ee133f41-d060-4f87-bca6-70cb870a9879' -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 2. /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/009f0193-08f1-4d5c-ac07-5b38331c5e84' -i -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Path parameters

Table 2. /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/R220/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" : "3cda5502-94a7-4780-943f-6b9e9f325475",
    "joined_at" : "2024-03-28T15:50:30.405005966Z",
    "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 2. /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 3. /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" : "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" : "root",
    "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 all root research fields

A GET requests lists all root research fields.

Curl request

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

HTTP response

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

{
  "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" : "root",
    "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 research field hierarchy

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

Curl request

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

HTTP response

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

{
  "content" : [ {
    "parent_ids" : [ "parent" ],
    "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

parent_ids

Array

The ids of the parent research fields.

resource

Object

Resource representation of the research field resource.

Listing statistics about a research field

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

Curl request

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

HTTP response

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

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

Datasets & Benchmarks

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

Listing research fields with benchmarks

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

Curl request

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

HTTP response

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

{
  "content" : [ {
    "id" : "R80",
    "label" : "Field 1"
  } ],
  "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
}

Listing Benchmarks by Field

A GET request lists benchmarks under a certain research field.

Curl request

$ curl 'http://localhost:8080/api/benchmarks/summary/research-field/R98?sort=problem.id,ASC' -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: 991

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

Benchmark Summary

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

Curl request

$ curl 'http://localhost:8080/api/datasets/research-problem/R67?sort=totalModels,DESC' -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: 719

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

Benchmark Unpacked

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

Curl request

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

HTTP response

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

{
  "content" : [ {
    "code_urls" : [ "https://some-code-3.cool", "https://some-code-2.cool", "https://some-code-1.cool" ],
    "metric" : "Metric 2",
    "model_id" : "R57",
    "model_name" : "Model 1",
    "paper_id" : "R52",
    "paper_month" : null,
    "paper_title" : "paper",
    "paper_year" : null,
    "score" : "4548"
  }, {
    "code_urls" : [ "https://some-code-3.cool", "https://some-code-2.cool", "https://some-code-1.cool" ],
    "metric" : "Metric 1",
    "model_id" : "R57",
    "model_name" : "Model 1",
    "paper_id" : "R52",
    "paper_month" : null,
    "paper_title" : "paper",
    "paper_year" : null,
    "score" : "2.55"
  } ],
  "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
}

Reproducibility Score

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

License

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

The endpoint currently only supports GitHub repository URIs.

Curl request

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

HTTP response

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

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

ORKG Widget

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

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

Curl request

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

Request parameters

Parameter Description

doi

The DOI of the resource to search.

title

The title of the resource to search.

Response fields

Path Type Description

id

String

The identifier of the resource.

doi

String

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

title

String

The title of the resource.

class

String

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

num_statements

Number

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

Statistics

Statistics are a way to obtain valuable information about the state of the graph. Every data point is provided by a predefined metric, which are organized in groups.

Listing groups

A GET request provides a list of all available metric groups.

Curl request

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

Response fields

Path Type Description

*

Object

The name of the group.

*.href

String

The URI of the group, which can be used to fetch a list of available metrics that are associated with this group.

Listing metrics of a group

A GET request provides a list of all available metrics of a given group.

Curl request

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

Response fields

Path Type Description

*

Object

The name of the metric.

*.href

String

The URI of the metric, which can be used to fetch information about the metric and its current value.

Fetching a metric

A GET request provides information about a given metric within a group.

Curl request

$ curl 'https://incubating.orkg.org/api/statistics/group1/metric1' -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: 109

{
  "description" : "Description of the metric.",
  "group" : "group1",
  "name" : "metric1",
  "value" : 1
}

Response fields

Path Type Description

name

String

The name of the metric.

description

String

The description of the metric.

group

String

The group of the metric.

value

Number

The value of the metric.

Identifiers

This section lists the supported identifiers for content-type endpoints.

Document identifiers

Name Key Predicate ID

DOI

doi

P26

Author identifiers

Name Key Predicate ID

ORCID

orcid

HAS_ORCID

Google Scholar author ID

google_scholar

googleScholarID

Research Gate profile ID

research_gate

researchGateID

LinkedIn personal profile ID

linked_in

linkedInID

Wikidata Identifier

wikidata

P76020

Web of Science ID

web_of_science

P58083

Visibility filter

Most content types support visibility filtering. The filtering is supported in GET requests via the "visibility" request parameter:

Request parameters

Parameter Description

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

Visibility filtering (obsolete)

To be backwards compatible, some endpoints support visibility filtering via additional request parameters in addition to the visibility request parameter. If the visibilty request parameter is used, both featured and unlisted are ignored. If it is absent, it will be set according to the values of the two parameters.

The use of these request parameters is deprecated and may be removed at some point. Clients are encouraged to transition to using the mechanism described in Visibility filter.

Request parameters

Parameter Description

featured

Return only featured results. Defaults to false. (Deprecated. See Visibility filter.)

unlisted

Return only unlisted results. Defaults to false. (Deprecated. See Visibility filter.)

Filter Configs

A filter config is an url-encoded json-list of search filters. They can be used to make advanced search queries on papers, providing a way for users to find the papers they are actually interested in. Each search filter is of the following structure:

{
  "exact" : true,
  "path" : [ "P105059", "P60013" ],
  "range" : "Pattern",
  "values" : [ {
    "op" : "EQ",
    "value" : "some value"
  } ]
}
Path Type Description

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. For example the path provided in the example above matches node n in the following graph: (:Paper)-[P31]→(:Contribution)-[P105059]→(:Thing)-[P60013]→(n:Thing)

range

String

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

values

Array

A list that contains the actual values that should be matched. Multiple entries are logically combined with an OR operation, while multiple filter configs are logically combined with an AND operation.

values[].op

String

The logical matching operation.

values[].value

String

The value that needs to match.

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 is limited to 10, including the length of the specified path, starting from the contribution node.

Opcode Operation

EQ

Equals

NE

Not equals

LT

Less than

LE

Less or equal than

GE

Greater than

GT

Greater or equal than

Sorting and Pagination

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

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

Parameter Description

page

The page number requested, 0-indexed.

size

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

sort

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

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

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

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

Table 3. Sorting keys allowed by the API
Key Description

For sorting resources

id

The id of the resource

label

The label of the resource

created_at

The datetime timestamp of the creation

created_by

The id of the curator who originally created the resource

visibility

The visibility of the resource

For sorting predicates, classes & literals

id

The id of the predicate, class or literal

label

The label of the predicate, class or literal

created_at

The datetime timestamp of the creation

created_by

The id of the curator who originally created the predicate, class or literal

For sorting statements

id

The statement id

index

The index of the statement

created_at

The datetime timestamp of the creation

created_by

The id of the curator who originally created the statement

sub.id

The id of the subject

sub.label

The label of the subject

sub.created_at

The creation timestamp of the subject

sub.created_by

The id of the curator who originally created the subject of the statement

obj.id

The id of the object

obj.label

The label of the object

obj.created_at

The creation timestamp of the object

obj.created_by

The id of the curator who originally created the object of the statement

Representations

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

Basic Types

Timestamps

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

Errors

Path Type Description

status

Number

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

error

String

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

message

String

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

path

String

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

timestamp

String

The timestamp of when the error happened.

Pages

Path Type Description

content

Array

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

empty

Boolean

Determines if the current page is empty.

first

Boolean

Determines if the current page is the first one.

last

Boolean

Determines if the current page is the last one.

number

Number

The number of the current page.

numberOfElements

Number

The number of elements currently on this page.

size

Number

The size of the current page.

sort

Object

The sorting parameters for this page.

sort.empty

Boolean

Determines if the sort object is empty.

sort.sorted

Boolean

Determines if the page is sorted. Inverse of unsorted.

sort.unsorted

Boolean

Determines if the page is unsorted. Inverse of sorted.

totalElements

Number

The total amounts of elements.

totalPages

Number

The number of total pages.

Entities

Resource

Path Type Description

id

String

The identifier of the resource.

label

String

The label of the resource. It is intended to be read by humans and should be used for displaying the resource.

classes

Array

The set of classes of which this resources is an instance of.

shared

Number

The number of statements that have this resource in their object position.

featured

Boolean

Determine if the resource is featured. Defaults to false.

unlisted

Boolean

Determine if the resource is unlisted. Defaults to false.

verified

Boolean

Determine if the resource is verified. Defaults to false.

extraction_method

String

Determines how the resource was created. Can be one of AUTOMATIC, MANUAL, UNKNOWN.

observatory_id

String

The UUID of the observatory to which this resource belongs.

organization_id

String

The UUID of the organization to which this resource belongs.

created_at

OffsetDateTime

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

created_by

String

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

modifiable

Boolean

Whether this resource can be modified.

_class

String

An indicator which type of entity was returned. Always has the value resource.

Literal

Path Type Description

id

String

The identifier of the literal.

label

String

The literal value.

datatype

String

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

created_at

OffsetDateTime

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

created_by

String

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

modifiable

Boolean

Whether this literal can be modified.

_class

String

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