# Query a Knowledge Base

Use the **retrieve** API to query a Knowledge Base for information matching keywords or phrases.

When you query a knowledge base, you must submit a POST request:

1. Identify the Knowledge Base to query using its **code** in the URL of the request.
2. Specify the text to search the Knowledge Base for using the `text` parameter.
3. Specify filters to restrict the documents that are searched.

The API will return matching items (portions of legislation, judgment summaries) that match your query, including a score, the text of the portion, and metadata.

## 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: 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/ai-api/knowledge-bases/query-a-knowledge-base.md?ask=<question>
```

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.