{
    "openapi": "3.1.0",
    "info": {
        "title": "Citizen.ca public knowledge API",
        "version": "1.0",
        "description": "Read-only published knowledge with source fidelity, factual-accuracy reviews, revisions and separate rights. No API key required."
    },
    "servers": [
        {
            "url": "https://citizen.ca/wp-json/citizen/v1"
        }
    ],
    "paths": {
        "/knowledge": {
            "get": {
                "operationId": "listKnowledge",
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Language: en, fr, or all",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 2147483647
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Page size, maximum 100",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Search title/claim",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "topic",
                        "in": "query",
                        "description": "Knowledge-topic slug",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "updated_since",
                        "in": "query",
                        "description": "Inclusive ISO-8601 timestamp with timezone",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated collection",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "https://citizen.ca/data/schema.json"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "400": {
                        "description": "Invalid parameters"
                    }
                }
            }
        },
        "/knowledge/{reference}": {
            "get": {
                "operationId": "getKnowledge",
                "parameters": [
                    {
                        "name": "reference",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^CA-K[0-9]+$"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "en",
                                "fr"
                            ],
                            "default": "en"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Current published record",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "https://citizen.ca/data/schema.json"
                                }
                            }
                        }
                    },
                    "410": {
                        "description": "Previously public record withdrawn; minimal tombstone only"
                    },
                    "404": {
                        "description": "No previously public reference"
                    },
                    "409": {
                        "description": "Ambiguous public reference"
                    }
                }
            }
        },
        "/changes": {
            "get": {
                "operationId": "getChanges",
                "parameters": [
                    {
                        "name": "after",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 500,
                            "default": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ordered additions, updates and withdrawals; persist next_cursor and follow has_more."
                    }
                }
            }
        }
    }
}