API reference - Summary

The GEO Knowledge Hub API exposes a huge amount of endpoints. In day-to-day use you will only touch a small subset. To facilitate the usage of the API, this page provides a cheat sheet of the most-used endpoints.

This covers workflows associated for Knowledge Packages and Knowledge Resources. Specifically, workflows related to search, manage records (packages and resources), and many others.

Where this fits

This page is a cheat sheet. For step-by-step recipes that combine several endpoints, see the examples, specifically Publishing a Knowledge Resource and Publishing a Knowledge Package.

For the canonical list of every endpoint (parameters, schemas, errors), see the API reference.

Knowledge Packages

Search & discovery

• GET /api/packages Search / list published Knowledge Packages.
• GET /api/packages/{id} Get a published Knowledge Package by id.
• GET /api/user/packages List the current user's drafts and published Packages.

Drafts

• POST /api/packages Create a Knowledge Package draft.
• GET /api/packages/{id}/draft Get a Knowledge Package draft.
• PUT /api/packages/{id}/draft Update a draft's metadata.
• POST /api/packages/{id}/draft Open a draft from a published Package (edit in place).
• DELETE /api/packages/{id}/draft Delete / discard a draft.

Draft files

• GET /api/packages/{id}/draft/files List files attached to a draft.
• POST /api/packages/{id}/draft/files Initialise file uploads (one entry per file).
• PUT /api/packages/{id}/draft/files/{filename}/content Upload the binary file content.
• POST /api/packages/{id}/draft/files/{filename}/commit Commit a completed file upload.
• DELETE /api/packages/{id}/draft/files/{filename} Delete a draft file.

Publish

• POST /api/packages/{id}/draft/actions/publish Publish the draft (mints DOI, makes the Package public).

Versions

• GET /api/packages/{id}/versions List all versions of a Knowledge Package.
• POST /api/packages/{id}/versions Create a new version (opens a fresh draft).
• GET /api/packages/{id}/versions/latest Get the latest version of a Package.
• POST /api/packages/{id}/draft/actions/resources-import Import Resources from the previous version into the new draft.

Resource association

Link Knowledge Resources into a Package — first to its context, then to the current draft.

• GET /api/packages/{id}/draft/resources List Resources currently in this draft.
• POST /api/packages/{id}/context/actions/associate Associate Resources with the Package context.
• POST /api/packages/{id}/context/actions/dissociate Remove Resources from the Package context.
• POST /api/packages/{id}/draft/resources Add Resources to the current draft.
• DELETE /api/packages/{id}/draft/resources Remove Resources from the current draft.

Knowledge Resources

Search & discovery

• GET /api/records Search / list published Knowledge Resources.
• GET /api/records/{id} Get a published Knowledge Resource by id.
• GET /api/user/records List the current user's drafts and published Resources.

Drafts

• POST /api/records Create a Knowledge Resource draft.
• GET /api/records/{id}/draft Get a Knowledge Resource draft.
• PUT /api/records/{id}/draft Update a draft's metadata.
• DELETE /api/records/{id}/draft Delete / discard a draft.

Draft files

• GET /api/records/{id}/draft/files List files attached to a draft.
• POST /api/records/{id}/draft/files Initialise file uploads (one entry per file).
• PUT /api/records/{id}/draft/files/{filename}/content Upload the binary file content.
• POST /api/records/{id}/draft/files/{filename}/commit Commit a completed file upload.
• DELETE /api/records/{id}/draft/files/{filename} Delete a draft file.

Publish & versions

• POST /api/records/{id}/draft/actions/publish Publish a standalone Resource. Resources attached to a Package are published with their Package.
• GET /api/records/{id}/versions List all versions of a Knowledge Resource.
• POST /api/records/{id}/versions Create a new version (opens a fresh draft).

Unified search

Cross-entity search

Query Packages and Resources together in a single request.

• GET /api/search Search across both Packages and Resources.

See the Search examples page for common query patterns (full-text, bounding box, field filters).