> For the complete documentation index, see [llms.txt](https://docs.riskbase.uk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riskbase.uk/riskbase-docs/api/assessments.md).
# Assessments
## Get Assessments
> Get a list of assessments produced for your organisation or produced by your organisation.
````json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments":{"get":{"tags":["Assessments"],"summary":"Get Assessments","description":"Get a list of assessments produced for your organisation or produced by your organisation.\n","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","default":1},"in":"query","name":"page"},{"schema":{"type":"string"},"in":"query","name":"assessment","description":"Comma separated assessment IDs"},{"schema":{"type":"string"},"in":"query","name":"property","description":"Comma separated property IDs"},{"schema":{"type":"string"},"in":"query","name":"type","description":"Comma separated assessment types
See `GET /assessments/types`"},{"schema":{"type":"string","default":"For,By"},"in":"query","name":"performed","description":"```For```: list assessments produced **for** your organisation. ```By```: list assessments produced **by** your organisation\n"},{"schema":{"type":"string","default":"approved"},"in":"query","name":"status","description":"Comma separated assessment statuses\n"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeflags","description":"Include assessment flags and their history"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"total":{"type":"integer"},"assessments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"property":{"type":"string","description":"ID of property this assessment belongs to"},"asset":{"type":"string","deprecated":true,"description":"Use `property` instead"},"forOrganisation":{"type":"string","description":"ID of organisation the assessment was created for"},"byOrganisation":{"type":"string","description":"ID of organisation that created the assessment"},"reference":{"type":"string"},"customReference":{"type":"string"},"type":{"type":"string","description":"See `GET /assessments/types`"},"status":{"type":"string","enum":["inprogress","submitted","approved"]},"assessedDate":{"type":"date","format":"Y-m-d"},"approvedDate":{"type":"date","format":"Y-m-d"},"expiryDate":{"type":"date","format":"Y-m-d"},"flags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currentState":{"type":["object","null"],"properties":{"isSet":{"type":"boolean"},"user":{"type":"string","format":"UID"},"comment":{"type":"string"},"timestamp":{"type":"timestamp","format":"Y-m-d H:i:s"}}},"history":{"type":"array","items":{"type":"object","properties":{"isSet":{"type":"boolean"},"user":{"type":"string","format":"UID"},"comment":{"type":"string"},"timestamp":{"type":"timestamp","format":"Y-m-d H:i:s"}}}}}}}}}},"organisations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"county":{"type":"string"},"postcode":{"type":"string"}}}}}}}}}}}}}}}}
````
## GET /assessments/types
> Get Assessment Types
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/types":{"get":{"tags":["Assessments"],"summary":"Get Assessment Types","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"types":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"isDeleted":{"type":"boolean"}}}}}}}}}}}}}}
```
## Get Assessment Report PDF
> Get an assessment's report PDF
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/{assessmentId}/report.pdf":{"get":{"tags":["Assessments"],"summary":"Get Assessment Report PDF","description":"Get an assessment's report PDF","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"assessmentId","required":true}],"responses":{"200":{"content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}}}}}}}
```
## Get Assessment Bundle ZIP
> Get an assessment's bundle ZIP. This bundle contains:\
\
> • Report PDF\
> • CSVs of actions, controls, and elements\
> • Assessment attachments\
> • Images and files for actions, controls, and elements
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/{assessmentId}/bundle.zip":{"get":{"tags":["Assessments"],"summary":"Get Assessment Bundle ZIP","description":"Get an assessment's bundle ZIP. This bundle contains:
\n• Report PDF\n• CSVs of actions, controls, and elements\n• Assessment attachments\n• Images and files for actions, controls, and elements\n","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"assessmentId","required":true}],"responses":{"200":{"content":{"application/zip":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}}}}}}}
```
## Get Assessment Schedules
> Get a list of assessment schedules
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/schedules":{"get":{"tags":["Assessments"],"summary":"Get Assessment Schedules","description":"Get a list of assessment schedules\n","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","default":1},"in":"query","name":"page"},{"schema":{"type":"string","format":"UID"},"in":"query","name":"property","description":"Comma separated property IDs"},{"schema":{"type":"string"},"in":"query","name":"asset","deprecated":true,"description":"Use `property` instead"},{"schema":{"type":"string","format":"UID"},"in":"query","name":"type","description":"Comma separated assessment types
See `GET /assessments/types`"},{"schema":{"type":"string","enum":["notstarted","inprogress"],"default":"notstarted,inprogress"},"in":"query","name":"status","description":"Comma separated schedule statuses"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"total":{"type":"integer"},"schedules":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","format":"UID","description":"ID of property this schedule belongs to"},"asset":{"type":"string","format":"UID","deprecated":true,"description":"Use `property` instead"},"type":{"type":"string","format":"UID","description":"See `GET /assessments/types`"},"status":{"type":"string","enum":["notstarted","inprogress"]},"dueDate":{"type":"date","format":"Y-m-d"},"description":{"type":"string"},"customReference":{"type":"string"},"assignedUsers":{"type":"array","items":{"type":"string","format":"UID"}}}}}}}}}}}}}}}
```
## Get Assessment Schedule
> Get a property's assessment schedule for a particular assessment type
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/schedules/{property}/{type}":{"get":{"tags":["Assessments"],"summary":"Get Assessment Schedule","description":"Get a property's assessment schedule for a particular assessment type","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"property","description":"The schedule's property ID","required":true},{"schema":{"type":"string","format":"UID"},"in":"path","name":"type","description":"The schedule's assessment type ID","required":true}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"property":{"type":"string","format":"UID","description":"ID of property this schedule belongs to"},"asset":{"type":"string","format":"UID","deprecated":true,"description":"Use `property` instead"},"type":{"type":"string","format":"UID","description":"See `GET /assessments/types`"},"status":{"type":"string","enum":["notstarted","inprogress"]},"dueDate":{"type":"date","format":"Y-m-d"},"description":{"type":"string"},"customReference":{"type":"string"},"assignedUsers":{"type":"array","items":{"type":"string","format":"UID"}}}}}}},"400":{"content":{"application/json":{"schema":{"oneOf":[{"title":"PropertyNotFound","properties":{"code":{"type":"PropertyNotFound"}}},{"title":"AssessmentTypeNotFound","properties":{"code":{"type":"AssessmentTypeNotFound"}}}]}}}},"404":{"content":"application/json","description":"No schedule found"}}}}}}
```
## Create/Update Assessment Schedule
> Update a property's assessment schedule if it exists, otherwise create it
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/schedules/{property}/{type}":{"put":{"tags":["Assessments"],"summary":"Create/Update Assessment Schedule","description":"Update a property's assessment schedule if it exists, otherwise create it","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"property","description":"The schedule's property ID","required":true},{"schema":{"type":"string","format":"UID"},"in":"path","name":"type","description":"The schedule's assessment type ID","required":true}],"requestBody":{"content":{"application/json":{"schema":{"required":["status"],"properties":{"dueDate":{"type":"date","format":"Y-m-d"},"description":{"type":"string"},"customReference":{"type":"string","description":"The schedule's custom reference will appear on the assessment as `scheduleCustomReference` in `GET /assessments`\n"},"assignedUsers":{"type":"array","items":{"type":"string","format":"UID"}}}}}}},"responses":{"204":{"content":"application/json"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"title":"PropertyNotFound","properties":{"code":{"type":"PropertyNotFound"}}},{"title":"AssessmentTypeNotFound","properties":{"code":{"type":"AssessmentTypeNotFound"}}},{"title":"UserNotFound","properties":{"code":{"type":"UserNotFound"},"error":{"type":"Invalid assigned users [...]"}}},{"title":"DateInvalid","properties":{"code":{"type":"DateInvalid"},"error":{"type":"Invalid due date"}}}]}}}}}}}}}
```
## Delete Assessment Schedule
> Delete a property's assessment schedule
```json
{"openapi":"3.1.1","info":{"title":"RiskBase API","version":"0.0.1"},"tags":[{"name":"Assessments","description":""}],"servers":[{"url":"https://api3.riskbase.uk"}],"security":[{"Bearer Authentication":[]}],"components":{"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer {AuthorizationToken}`"}}},"paths":{"/assessments/schedules/{property}/{type}":{"delete":{"tags":["Assessments"],"summary":"Delete Assessment Schedule","description":"Delete a property's assessment schedule","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"property","description":"The schedule's property ID","required":true},{"schema":{"type":"string","format":"UID"},"in":"path","name":"type","description":"The schedule's assessment type ID","required":true}],"responses":{"204":{"content":"application/json"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"title":"PropertyNotFound","properties":{"code":{"type":"PropertyNotFound"}}},{"title":"AssessmentTypeNotFound","properties":{"code":{"type":"AssessmentTypeNotFound"}}}]}}}}}}}}}
```
---
# 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://docs.riskbase.uk/riskbase-docs/api/assessments.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.