Public Search API Documentation

Overview

The Climate Insights Directory Public Search API allows AI agents, researcher scripts, and automated tools to discover and cite civil-society climate documents. The API endpoints follow RFC 9457 Problem Details for HTTP APIs.

Stability policy: The current stability stage is beta. Breaking changes will be announced at least 10 days in advance (Terms of Use 8.2). Result ranking and ordering changes are not breaking changes. See Versioning and deprecation.

Versioning and deprecation

A breaking change is one that stops an existing client from working, such as renaming or removing a parameter or a response field, or changing a field's type. Changes to result ranking or order are not breaking. A breaking change follows these steps:

1. It is announced in the Changelog on this page at least 10 days before the current version stops answering.
2. The new version ships at a new path, /api/v2/search, while/api/v1/search keeps answering, so both versions are live at the same time.
3. During that window /api/v1/search answers as before, and every response carries a Deprecation header (the version is deprecated) and aSunset header (the date it stops answering).
4. After the Sunset date, /api/v1/search answers410 Gone with a Problem Details body that links to the new version.

Endpoints

• GET /api/v1/search - Primary search endpoint
• POST /api/mcp - Model Context Protocol (MCP) endpoint
• GET /api/v1/openapi.json - OpenAPI 3.1 specification document
• GET /.well-known/api-catalog - RFC 9727 API Catalog
• GET /opensearch.xml - OpenSearch 1.1 description

Parameters

The search endpoint accepts 16 parameters. Unknown parameters return a 400 Problem Details response.

Example Request and Response

Request URL combining a field operator inside q and a repeated facet:

GET https://climateinsightsdirectory.org/api/v1/search?q=flooding+intitle%3Ajamaica&climate_tags=Adaptation&climate_tags=Mitigation

Abbreviated 200 OK response body:

{
  "query_echo": {
    "q": "climate",
    "filters": {},
    "warnings": []
  },
  "total": {
    "value": 1,
    "relation": "eq"
  },
  "page": 1,
  "page_size": 20,
  "self": "https://climateinsightsdirectory.org/api/v1/search?q=climate",
  "stability": "beta",
  "ai_marking": {
    "digital_source_type": {
      "uri": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
      "name": "Created using Generative AI"
    },
    "notice": "Summary and key insights are generated using artificial intelligence."
  },
  "results": [
    {
      "id": "cape-ca-001",
      "url": "https://climateinsightsdirectory.org/document/cape-ca-001",
      "title": "Sample Document",
      "publisher": {
        "name": "CAPE",
        "organization": "cape"
      },
      "document_type": "report",
      "language": "en",
      "date_published": "2026-01-01",
      "source_url": "https://example.org/doc.pdf",
      "generator": "Climate Insights Directory",
      "generated_fields": [
        "summary"
      ]
    }
  ]
}

AI Marking and Provenance

To ensure transparency for downstream AI agents and research tools, the API distinguishes human-curated and publisher-extracted metadata from AI-generated fields:

• ai_marking: Top-level object declaring overall AI provenance using IPTC Digital Source Type metadata (trainedAlgorithmicMedia) and a standard disclosure notice.
• generated_fields: Array of field names on each result item (such as summary, key_insights, or facet tags) that were generated or enriched by language models.
• ai_generated: Boolean flag on an individual AiUnit (e.g. summary or items in key_insights), set to true when the text was machine-generated.
• unit: Identifier or fragment URI on an AiUnit linking the generated text to its specific anchor on the document record (e.g. {id}#summary or{id}#insight-1).
• date_modified: date string in YYYY-MM-DD form (or null) indicating when the AI-generated unit was last generated or modified.

Model Context Protocol (MCP) Endpoint

The Climate Insights Directory provides a Streamable HTTP MCP endpoint at https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp. It exposes two tools for AI agents:search and fetch.

Tools

Client Setup

https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp

claude mcp add --transport http climate-insights-directory "https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp"

https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp

gemini mcp add --transport http climate-insights-directory "https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp"

{
  "mcpServers": {
    "climate-insights-directory": {
      "serverUrl": "https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp"
    }
  }
}

hermes mcp add climate-insights-directory --url "https://climateinsightsdirectory.org/api/mcp?utm_source=docs&utm_medium=mcp"

Error Types (RFC 9457)

"type": "https://climateinsightsdirectory.org/api-docs#unknown-parameter"

"type": "https://climateinsightsdirectory.org/api-docs#invalid-parameter-value"

"type": "https://climateinsightsdirectory.org/api-docs#result-window-exceeded"

"type": "https://climateinsightsdirectory.org/api-docs#record-not-found"

"type": "https://climateinsightsdirectory.org/api-docs#record-withdrawn"

Changelog

• 2026-10-14: Added Model Context Protocol (MCP) endpoint (/api/mcp) providing search and fetch tools.
• 2026-10-05: Initial release of Public Search API v1 (beta). Added OpenAPI 3.1 specification, RFC 9727 linkset, OpenSearch 1.1, and RFC 9457 error handling.