> For the complete documentation index, see [llms.txt](https://developers.laws.africa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.laws.africa/knowledge-bases/reference/query-a-knowledge-base.md). # Query a Knowledge Base Use the retrieve endpoint to query a Knowledge Base for legal information that matches keywords, phrases or AI-generated search text. The request must: 1. identify the Knowledge Base by `code` in the URL; 2. include the `text` to search for; 3. optionally include `top_k` and `filters`. The response returns matching items with text, metadata and a score. ## Query the knowledge base for matching items. > Retrieve items from the knowledge base that match your query. ```json {"openapi":"3.0.3","info":{"title":"Laws.Africa Content API","version":"20.0.0 (v1)"},"security":[{"cookieAuth":[]},{"tokenAuth":[]},{"tokenAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"},"tokenAuth":{"type":"http","scheme":"bearer"}},"schemas":{"KnowledgeBaseRetrieveRequest":{"type":"object","description":"Details to retrieve items from a knowledge base.","properties":{"text":{"type":"string","description":"The text to find matching items for"},"top_k":{"type":"integer","maximum":100,"minimum":1,"default":10,"description":"Number of results to return"},"filters":{"properties":{"work_frbr_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Work Frbr Uri"},"work_frbr_uri__in":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Work Frbr Uri In"},"expression_frbr_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Expression Frbr Uri"},"expression_frbr_uri__in":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Expression Frbr Uri In"},"frbr_place":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Frbr Place"},"frbr_place__in":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Frbr Place In"},"frbr_doctype":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Frbr Doctype"},"frbr_doctype__in":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Frbr Doctype In"},"frbr_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Frbr Subtype"},"frbr_subtype__in":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Frbr Subtype In"},"repealed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Repealed"},"commenced":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Commenced"},"principal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Principal"}},"title":"KnowledgeBaseFilters","type":"object"}},"required":["text"]},"KnowledgeBaseRetrieveResponse":{"type":"object","description":"Items retrieved from a knowledge base.","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseItem"}}},"required":["results"]},"KnowledgeBaseItem":{"type":"object","description":"A knowledge base item.","properties":{"content":{"$ref":"#/components/schemas/KnowledgeBaseItemContent"},"metadata":{"$ref":"#/components/schemas/KnowledgeBaseItemMetadata"},"score":{"type":"number","format":"double","maximum":1,"minimum":0,"description":"The similarity score of the item (lower is better)"}},"required":["content","metadata","score"]},"KnowledgeBaseItemContent":{"type":"object","description":"The content of a knowledge base item.","properties":{"text":{"type":"string","description":"The text content of the item"}},"required":["text"]},"KnowledgeBaseItemMetadata":{"type":"object","description":"Metadata about a knowledge base item.","properties":{"work_frbr_uri":{"type":"string","description":"Work FRBR URI for the work the item belongs to"},"frbr_place":{"type":"string","description":"FRBR place code"},"frbr_country":{"type":"string","description":"FRBR country code"},"frbr_doctype":{"type":"string","description":"FRBR document type"},"frbr_subtype":{"type":"string","description":"FRBR document subtype"},"title":{"type":"string","description":"Title of the document the item belongs to"},"repealed":{"type":"boolean","description":"Is the work repealed? Legislation only."},"commenced":{"type":"boolean","description":"Is the work commenced? Legislation only."},"principal":{"type":"boolean","description":"Is the work a principal work? Legislation only."},"blurb":{"type":"string","description":"A short one-sentence summary of the document (Judgments only)."},"flynote":{"type":"string","description":"A flynote (key phrases) for the document (Judgments only)."},"expression_date":{"type":"string","format":"date","description":"Expression date of the document"},"expression_frbr_uri":{"type":"string","description":"Expression FRBR URI for the document the item belongs to"},"public_url":{"type":"string","description":"Public URL to access the document"},"portion_type":{"allOf":[{"$ref":"#/components/schemas/PortionTypeEnum"}],"description":"Type of the portion\n\n* `page` - page\n* `provision` - provision\n* `text` - text\n* `summary` - summary"},"portion_id":{"type":"string","description":"Identifier of the portion. A page number when type=page, an eid when type=portion."},"portion_title":{"type":"string","description":"Title of the portion"},"portion_parent_ids":{"type":"array","items":{"type":"string"},"description":"List of parent portion IDs, from top downwards"},"portion_parent_titles":{"type":"array","items":{"type":"string"},"description":"List of parent portion titles, from top downwards"},"portion_public_url":{"type":"string","description":"Public URL to access the portion"}},"required":["expression_date","expression_frbr_uri","frbr_country","frbr_doctype","frbr_place","frbr_subtype","portion_type","public_url","title","work_frbr_uri"]},"PortionTypeEnum":{"enum":["page","provision","text","summary"],"type":"string","description":"* `page` - page\n* `provision` - provision\n* `text` - text\n* `summary` - summary"}}},"paths":{"/ai/v1/knowledge-bases/{code}/retrieve":{"post":{"operationId":"knowledge_bases_retrieve_create","description":"Retrieve items from the knowledge base that match your query.","summary":"Query the knowledge base for matching items.","parameters":[{"in":"path","name":"code","schema":{"type":"string","description":"Unique code identifying this knowledge base"},"required":true}],"tags":["knowledge-bases"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseRetrieveRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseRetrieveRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseRetrieveRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseRetrieveResponse"}}},"description":""}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.laws.africa/knowledge-bases/reference/query-a-knowledge-base.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.