REST API

The GEO Knowledge Hub follows a REST-API-first approach: every operation available through the web interface is also exposed as Rest endpoints. This means that activities available in the Web UI, such as create drafts, uploading files, managing packages and resources, are backed by a Rest API. Users are able and encouraged to interact with the Rest API, as this can be used to automate tasks and integrate the GEO Knowledge Hub within their workflows or systems.

In the general, there are three main installation paths. They are presented below and detailed in the following sub-pages:

Concepts & lifecycles

Knowledge Packages, Knowledge Resources and Communities — what they are and how they move from draft to publish.

Examples

End-to-end recipes for publishing Resources and Packages, plus the most-used search query patterns.

Common endpoints

Cheat sheet of the most-used Records, Packages and Search operations, deep-linked into the OpenAPI reference.

API reference

Interactive OpenAPI references for Records, Events, Metrics and Vocabularies (coming soon).

Base URL

In this documentation, paths are written relative to the GEO Knowledge Hub production instance:

https://gkhub.earthobservations.org/api

For local or custom InvenioRDM-based deployments, replace the host with your own (the API surface is identical).

Authentication

Public read endpoints (e.g. searching or downloading a published Package or Resource) do not require authentication. Anything that touches drafts, files, or user data requires authentication.

To authenticate, users are able to use a personal access token. This token guides anyone with it, the rights to interact with the GEO Knowledge Hub on behalf of the user who generated it.

During requests, for authorization, the token is sent as a Bearer token in the Authorization header:

GET /api/user/records HTTP/1.1
Host: gkhub.earthobservations.org
Authorization: Bearer <your-token>
Accept: application/json

Users can generate a token in their user profile page.

API surfaces at a glance

The platform exposes several APIs, each documented as its own OpenAPI spec:

Records API: Knowledge Packages, Knowledge Resources, files, versions, package-resource associations, and unified search.

Events API: Training sessions, workshops, webinars and other community events surfaced on the platform.

Metrics API: Aggregated KPIs that power the public stats report.

Vocabularies API: Controlled vocabularies (languages, licenses, GEO Work Programme activities, engagement priorities, target audiences). The dedicated OpenAPI page is in progress.

Endpoints that are inherited unchanged from InvenioRDM (Communities, Groups, Members, etc.) follow the upstream contract — please consult the InvenioRDM REST API documentation for those.

Conventions used on this site

• Path placeholders are written in curly braces: /api/packages/{id}.
• Code samples default to the HTTP wire format. Where useful, a cURL tab is provided alongside.
• Identifiers shown in examples (e.g. 4d0ns-ntd89, jyrxf-fd296) are illustrative. Replace them with the IDs returned by your own requests.
• Response bodies are abbreviated with ... when a field’s exact contents are not relevant to the operation being shown.