GGKP Knowledge Brokerage API

Introduction

The GGKP Knowledge Brokerage API is the programmatic interface to the Green Growth Knowledge Platform's knowledge network. It enables partner organisations to connect their content management systems to a shared infrastructure for taxonomy management, federated search, automated classification, and conversational knowledge navigation. Built around a standardised green and circular economy taxonomy of over 2,800 terms, the API provides the integration layer through which platform partners manage, classify, and surface verified knowledge across the GGKP ecosystem.

Core Purpose

The primary goal of this API is to serve as a bridge between vast repositories of information and the users who need to access and utilize this knowledge effectively. It aims to:

Streamline knowledge organization — Provide a unified, hierarchical taxonomy system that standardizes how green growth knowledge is categorized across all partner platforms

Enhance discoverability — Enable powerful search capabilities that span multiple databases and content management systems, making knowledge findable regardless of where it resides

Automate content classification — Leverage artificial intelligence to automatically tag and categorize documents, reducing manual effort while ensuring consistency

Provide intelligent assistance — Offer domain-specific AI assistants that can answer questions, provide recommendations, and guide users to relevant resources

Architecture Overview

The API follows a layered architecture pattern that separates concerns between client access, security, business logic, and data persistence. All client requests flow through a centralized API gateway that handles authentication and routing before reaching the appropriate service layer.

Key Components

The API is structured around four main service categories, each addressing a crucial aspect of knowledge brokerage. Together, these components form an integrated ecosystem for managing the complete lifecycle of knowledge resources.

1. Taxonomy Management

The Taxonomy Management service is the backbone of knowledge organization within the GGKP ecosystem. It maintains a comprehensive, hierarchical vocabulary of standardized terms that are used to categorize all knowledge resources across the platform. The GGKP Taxonomy can be explored at https://taxonomy.ggkp.org/vocab/tree-graph.php .

Purpose and Scope

The taxonomy provides a shared language for describing green growth knowledge, ensuring that content from different sources can be consistently categorized and cross-referenced. The system organizes terms into distinct branches, each serving a specific classification purpose:

Sectors — Economic and industrial sectors (e.g., Manufacturing, Agriculture, Energy, Transport, Construction)

Themes — Cross-cutting topics and focus areas (e.g., Circular Economy, Climate Change, Biodiversity, Resource Efficiency)

Regions — Geographic classifications from global to national level (e.g., Africa, Asia-Pacific, Europe, Latin America)

Actors — Stakeholder categories (e.g., Government, Private Sector, Civil Society, Academia)

Knowledge Types — Document classifications (e.g., Policy Brief, Case Study, Research Paper, Toolkit)

Available Operations

The taxonomy service supports retrieval operations that allow clients to access the complete taxonomy structure or specific subsets based on domain context.

Method	Endpoint	Description
GET	`/taxonomy-manage/taxonomy`	Retrieves the complete master taxonomy with all terms organized in their hierarchical structure. Returns all branches including Sectors, Themes, Regions, Actors, and Knowledge Types.
GET	`/taxonomy-manage/view-termbyid`	Retrieves detailed information about a specific taxonomy term using its unique identifier. Useful for looking up term metadata and relationships.
GET	`/taxonomy-manage/view-domainname-data`	Retrieves a filtered taxonomy containing only the terms relevant to a specific GGKP domain (e.g., Green Industry Platform, Green Finance Platform).

Domain Support

The taxonomy can be filtered by domain to retrieve only relevant classification options:

ID	Code	Domain Name
1	GIP	Green Industry Platform
2	GFP	Green Finance Platform
3	GPP	Green Policy Platform
6	ISLANDS	GEF ISLANDS
7	FORUM	Green Forum
8	FARM	GEF FARM
9	NIP	GEF NIP
10	UNIDO	UNIDO

2. Search Federator

The Search Federator service provides unified search capabilities across the entire GGKP knowledge network. It aggregates content from multiple connected databases and content management systems, enabling users to discover relevant resources through a single query interface.

Purpose and Scope

Traditional search systems are limited to a single repository, creating knowledge silos that prevent users from discovering relevant content held by partner organizations. The Search Federator solves this problem by:

Unifying access — Providing a single search endpoint that queries all connected sources simultaneously

Semantic understanding — Offering AI-powered search that understands the meaning and context of queries, not just keyword matching

Source management — Allowing partners to register their repositories and contribute content to the federated index

Content lifecycle — Supporting the full lifecycle of knowledge products from ingestion through indexing to deletion

Available Operations

The search service provides both query operations for discovering content and administrative operations for managing sources and products.

Search Operations:

Method	Endpoint	Description
POST	`/search-federator/search`	Executes a federated keyword search across all connected databases and content management systems. Returns ranked results based on relevance scoring.
POST	`/search-federator/semantic`	Performs AI-powered semantic search using natural language processing. Understands query intent and returns contextually relevant results even when exact keywords don't match.

Source Management:

Method	Endpoint	Description
GET	`/search-federator/sources`	Lists all data sources currently connected to the federated search network, including metadata about each source's scope and content volume.
POST	`/search-federator/upload-source`	Registers a new data source in the federated network. Partners use this to connect their repositories to the GGKP search infrastructure.

Product Management:

Method	Endpoint	Description
POST	`/search-federator/upload-products`	Uploads and indexes knowledge products for a registered source. Accepts product metadata including title, description, URL, and classification tags.
GET	`/search-federator/products/{source_id}`	Retrieves a listing of all knowledge products indexed for a specific source. Useful for auditing and synchronization purposes.
DELETE	`/search-federator/delete-products`	Removes one or more knowledge products from the search index. Supports batch deletion for efficient content management.

3. Automatic Classifier

The Automatic Classifier service leverages artificial intelligence to analyze document content and automatically assign appropriate taxonomy classifications. This dramatically reduces the manual effort required to categorize knowledge resources while ensuring consistent tagging across the platform.

Purpose and Scope

Manual content classification is time-consuming, inconsistent, and doesn't scale. The Automatic Classifier addresses these challenges by:

AI-powered analysis — Using machine learning models trained on the GGKP taxonomy to understand document content and context

Multi-dimensional classification — Assigning tags across multiple taxonomy branches simultaneously (Sectors, Themes, Regions, etc.)

Confidence scoring — Providing confidence scores for each classification, allowing human reviewers to focus attention where it's most needed

Content generation — Generating summaries and body text for documents, useful when only a title or PDF is available

Available Operations

Method	Endpoint	Description
POST	`/classify`	Classifies a PDF document using the GGKP taxonomy. Returns classifications with confidence scores and reasoning across all taxonomy branches.
POST	`/generate-body-summary`	Uses AI to generate descriptive body text and a concise summary for a knowledge product.

PDF Classification Endpoint

POST /classify

Automatically classifies a PDF document using the GGKP taxonomy. The classifier extracts text content from the PDF, analyzes it using AI models, and returns relevant taxonomy terms with confidence scores.

Request Format: multipart/form-data

Parameter	Type	Required	Default	Description
`file`	File	Yes	—	PDF file to classify. The service extracts text content for analysis.
`domain`	String	No	All	Domain ID(s) to filter taxonomy. Restricts classification to terms relevant to specific GGKP platforms.
`taxonomy`	String	No	All	Taxonomy branches to include in classification.
`threshold`	Float	No	`0.9`	Minimum confidence score (0.0-1.0). Results below this threshold are filtered out.
`max_results`	Integer	No	`3`	Maximum number of results to return per taxonomy category.
`include_scores`	Boolean	No	`true`	Whether to include confidence scores in the response.

Domain Parameter Formats:

The domain parameter accepts multiple formats for flexibility:

# Single domain by ID
domain=1
domain=2

# Single domain by code
domain=GIP
domain=GFP

# Multiple domains (comma-separated)
domain=1, 2
domain=GIP, GFP

# Multiple domains (JSON array)
domain=[1, 2, 3]

# Mixed format
domain=GIP, 2, GEF FARM

Domain Reference:

ID	Code	Domain Name
1	GIP	Green Industry Platform
2	GFP	Green Finance Platform
3	GPP	Green Policy Platform
6	ISLANDS	GEF ISLANDS
7	FORUM	Green Forum
8	FARM	GEF FARM
9	NIP	GEF NIP
10	UNIDO	UNIDO

Taxonomy Parameter:

Specify which taxonomy branches to evaluate. If omitted, all branches are used.

# Comma-separated
taxonomy=Sectors, Themes
taxonomy=Sectors, Themes, Regions

# JSON array
taxonomy=["Sectors", "Themes", "Regions"]

Available Taxonomy Branches:

Branch	Description	Examples
`Sectors`	Economic and industrial sectors	Manufacturing, Agriculture, Energy, Transport, Construction
`Themes`	Cross-cutting topics and focus areas	Circular Economy, Climate Change, Biodiversity, Resource Efficiency
`Regions`	Geographic classifications	Africa, Asia-Pacific, Europe, Latin America, Global
`Actors`	Stakeholder categories	Government, Private Sector, Civil Society, Academia
`Knowledge`	Document type classifications	Policy Brief, Case Study, Research Paper, Toolkit, Report
`Programme`	GGKP programmes	Programme-specific classifications
`Focus Area`	Specific focus areas	Detailed focus area classifications

Threshold Guidelines:

Value	Use Case
`0.9` (default)	High confidence only — fewer but more accurate results
`0.7 - 0.8`	Balanced — includes moderately confident classifications
`0.5 - 0.6`	Exploratory — includes uncertain classifications for review

Note: At least one result is always returned per category regardless of threshold setting.

Classification Output

The classifier returns structured results organized by taxonomy branch:

sectors — Identified economic sectors with confidence scores

themes — Relevant thematic areas and cross-cutting topics

regions — Geographic relevance at various levels

stakeholders — Target stakeholder groups

target_audiences — Intended reader categories

knowledge_types — Document type classification

Each classification includes:

name — The taxonomy term name

score — Confidence score (0.0 to 1.0), if include_scores=true

reasoning — AI-generated explanation for the classification

Example Response:

{
  "status": "success",
  "data": {
    "sectors": [
      {"name": "Manufacturing", "score": 0.95, "reasoning": "Document discusses industrial production processes"},
      {"name": "Energy", "score": 0.87, "reasoning": "References to renewable energy transitions"}
    ],
    "themes": [
      {"name": "Circular Economy", "score": 0.92, "reasoning": "Focus on waste reduction and recycling"}
    ],
    "regions": [
      {"name": "Asia Pacific", "score": 0.88, "reasoning": "Case studies from Asian countries"}
    ],
    "knowledge_types": [
      {"name": "Case Study", "score": 0.94, "reasoning": "Presents real-world implementation examples"}
    ]
  },
  "meta": {
    "config": {
      "active_taxonomy": ["Sectors", "Themes", "Regions", "Knowledge"],
      "threshold": 0.9,
      "max_results": 3
    },
    "total_time": 2.45
  }
}

4. Knowledge Assistants

The Knowledge Assistants service provides domain-specific conversational AI interfaces that can answer questions, provide recommendations, and guide users to relevant resources within the GGKP knowledge base.

Purpose and Scope

Traditional search requires users to formulate precise queries and sift through results. Knowledge Assistants offer a more natural interaction model by:

Natural language understanding — Accepting questions in plain language without requiring knowledge of search syntax or taxonomy structure

Domain expertise — Providing specialized assistants trained on specific knowledge domains for more accurate and relevant responses

Contextual responses — Generating answers that synthesize information from multiple sources, with citations to original documents

Customizable output — Supporting different response formats and styles to match integration requirements

Available Operations

Multiple assistant endpoints are available, each optimized for different use cases and knowledge domains.

Method	Endpoint	Description
POST	`/generic/api/generic`	General-purpose assistant that can answer questions across all GGKP knowledge domains. Suitable for broad queries that span multiple topics or when the specific domain is unknown.

Request Parameters

All assistant endpoints accept similar core parameters:

question — The user's question in natural language

user_type — Category of user making the request (used for response tailoring)

system — Optional system instructions for response customization

limit — Maximum number of source references to include

render — Output format specification (available on Typebot endpoint)

API Usage and Integration

The API is designed following RESTful principles, making it straightforward to integrate into web applications, mobile apps, and backend systems. All endpoints use standard HTTP methods and return JSON responses.

Base URL

https://api.ggkp.org

Authentication

All API requests require authentication using an API key passed in the request header:

api-key: your-api-key-here

API keys are issued by the GGKP technical team and are associated with specific permissions that control which operations can be performed.

Required Permissions

Different operations require different permission levels:

Permission	Description
Upload Source	Allows registering new data sources
Upload Products	Allows uploading and indexing knowledge products
Domain Sources	Allows listing and managing domain sources
List Products	Allows retrieving product listings

Response Format

All endpoints return JSON responses with a consistent structure:

{
  "status": "success",
  "data": { ... },
  "meta": {
    "processing_time": 1.23
  }
}

Error responses include descriptive messages:

{
  "status": "error",
  "message": "Description of the error",
  "code": 400
}

HTTP Status Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
500	Server Error	Internal server error

Use Cases

The GGKP API supports a wide range of integration scenarios:

Enterprise search enhancement — Integrate federated search into existing knowledge management systems to expand discovery across partner content

Content management augmentation — Add automatic classification to CMS workflows, reducing manual tagging effort and improving consistency

Chatbot development — Build conversational interfaces for websites and applications using the Knowledge Assistant endpoints

Data synchronization — Keep partner repositories synchronized with the GGKP index using the source and product management endpoints

Analytics and reporting — Leverage taxonomy and classification data to analyze content coverage and identify knowledge gaps

Mobile applications — Power mobile apps with search and assistant capabilities for field workers and researchers

Overview

GGKP Knowledge Brokerage API#

Introduction#

Core Purpose#

Architecture Overview#

Key Components#

1. Taxonomy Management#

Purpose and Scope#

Available Operations#

Domain Support#

2. Search Federator#

Purpose and Scope#

Available Operations#

3. Automatic Classifier#

Purpose and Scope#

Available Operations#

PDF Classification Endpoint#

Classification Output#

4. Knowledge Assistants#

Purpose and Scope#

Available Operations#

Request Parameters#

API Usage and Integration#

Base URL#

Authentication#

Required Permissions#

Response Format#

HTTP Status Codes#

Use Cases#

GGKP Knowledge Brokerage API

Introduction

Core Purpose

Architecture Overview

Key Components

1. Taxonomy Management

Purpose and Scope

Available Operations

Domain Support

2. Search Federator

Purpose and Scope

Available Operations

3. Automatic Classifier

Purpose and Scope

Available Operations

PDF Classification Endpoint

Classification Output

4. Knowledge Assistants

Purpose and Scope

Available Operations

Request Parameters

API Usage and Integration

Base URL

Authentication

Required Permissions

Response Format

HTTP Status Codes

Use Cases