List Knowledge Docs

List planning policy documents with filters and pagination.

Use this request to search the knowledge base and return document metadata in pages.

#Request

GET /ext/v1/knowledge/docs

#When To Use It

You need to browse the knowledge catalog.
You want to filter by jurisdiction, document type, or policy domain.
You need doc_id values for follow-up detail requests.

#Query Parameters

Parameter	Type	Required	Description	Example(s)
`jurisdiction`	string	No	Filter by planning system level or local authority. Use `National` for national guidance.	`National`, `Dublin City Council`
`document_type`	string	No	Filter by document type.	`Ministerial Guidelines`
`policy_domain`	string	No	Filter by planning policy domain or topic area.	`Housing standards & mix`
`limit`	integer	No	Maximum documents per request, from 1 to 100. Default is 20.	`50`
`offset`	integer	No	Result offset for pagination.	`0`

#Example Request

curl "https://api.eireplan.ie/ext/v1/knowledge/docs?jurisdiction=National&limit=2" \
  -H "Authorization: Bearer ek_your_api_key_here"

#Response Structure

Field	Type	Description
`documents`	array	List of knowledge documents matching the query.
`total`	integer	Total number of matching documents.
`limit`	integer	The applied page size.
`offset`	integer	The applied result offset.
`has_more`	boolean	Whether another page is available after this one.

Each item in documents includes:

Field	Type	Description
`doc_id`	string (UUID)	Stable document identifier.
`metadata.document_title`	string	Full official title.
`metadata.short_reference_name`	string	Short reference name for display.
`metadata.planning_system_level`	string	National, Regional, or Local.
`metadata.document_type`	string	Document classification.
`metadata.current_status`	string	Current document status.
`metadata.issuing_body_name`	string	Issuing authority or organization.
`metadata.key_policy_domains`	array	Main policy themes covered.
`base_url`	string	Official source URL.
`updated_at`	string	Last update timestamp in ISO 8601 format.

#Example Response

json

{
  "documents": [
    {
      "doc_id": "7af4c2d9-87ea-4887-8d8f-95e20b25a1a5",
      "metadata": {
        "document_title": "Sustainable Residential Development and Compact Settlements Guidelines",
        "short_reference_name": "SRD Guidelines",
        "planning_system_level": "National",
        "document_type": "Ministerial Guidelines",
        "current_status": "In force",
        "issuing_body_name": "Department of Housing, Local Government and Heritage",
        "key_policy_domains": ["Housing standards & mix", "Urban design & placemaking"]
      },
      "base_url": "https://www.gov.ie/example-guidelines",
      "updated_at": "2026-01-14T11:20:00Z"
    }
  ],
  "total": 42,
  "limit": 2,
  "offset": 0,
  "has_more": true
}

#Next Step

Use the returned doc_id with Get Knowledge Document when you want the complete record for a specific document.