> 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 /assessments/{assessmentId}/actions
> Get Assessment Actions
```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}/actions":{"get":{"tags":["Assessments"],"summary":"Get Assessment Actions","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"assessmentId","required":true},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page"},{"schema":{"type":"string"},"in":"query","name":"action","description":"Comma separated action IDs"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeusers","description":"Include names and emails of manually assigned users"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeteams","description":"Include names of manually assigned teams"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includecategories","description":"Include names of categories"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includeseverities","description":"Include names of severities"},{"schema":{"type":"boolean","default":false},"in":"query","name":"includetimescales","description":"Include names of timescales"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching actions before pagination"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"UID","description":"ID retained by the Task created when the assessment is approved"},"asset":{"type":["string","null"],"format":"UID","description":"ID of the assessment asset this action is linked to; null for a property-level action"},"reference":{"type":"string","format":"RB-XXXXXX"},"status":{"type":["string","null"],"format":"UID","description":"Status selected when reviewing an earlier action; null for a new action"},"what":{"type":"string"},"why":{"type":"string"},"location":{"type":"string"},"category":{"type":["string","null"],"format":"UID"},"severity":{"type":["string","null"],"format":"UID"},"timescale":{"type":["string","null"],"format":"UID"},"assignedTeams":{"type":"array","description":"Teams manually assigned in the assessment","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"manual":{"type":"boolean","description":"Always true"},"auto":{"type":"boolean","description":"Always false; automatic assignment occurs when the Task is created"}}}},"assignedUsers":{"type":"array","description":"Users manually assigned in the assessment","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"manual":{"type":"boolean","description":"Always true"},"auto":{"type":"boolean","description":"Always false; automatic assignment occurs when the Task is created"}}}},"photoIds":{"type":"array","description":"IDs accepted by the existing file endpoints","items":{"type":"string","format":"UID"}}}}},"users":{"type":"array","description":"Present if `includeusers=1`","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}}},"teams":{"type":"array","description":"Present if `includeteams=1`","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"name":{"type":"string"}}}},"categories":{"type":"array","description":"Present if `includecategories=1`","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"name":{"type":"string"}}}},"severities":{"type":"array","description":"Present if `includeseverities=1`","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"name":{"type":"string"}}}},"timescales":{"type":"array","description":"Present if `includetimescales=1`","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"name":{"type":"string"}}}}}}}}},"404":{"content":{"application/json":{"schema":{"oneOf":[{"title":"AssessmentNotFound","type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}}}]}}}}}}}}}
```
## GET /assessments/{assessmentId}/assets
> Get Assessment Assets
```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}`"}},"schemas":{}},"paths":{"/assessments/{assessmentId}/assets":{"get":{"tags":["Assessments"],"summary":"Get Assessment Assets","parameters":[{"schema":{"type":"string","format":"UID"},"in":"path","name":"assessmentId","required":true},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page"},{"schema":{"type":"string","format":"Comma-Separated: ID or name"},"in":"query","name":"type","description":"Limit the list by asset type ID or name"},{"schema":{"type":"string","format":"Comma-Separated: ID"},"in":"query","name":"id","description":"Limit the list by asset ID"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching assets before pagination"},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"UID"},"type":{"type":"string","description":"ID of asset type","format":"UID"},"fields":{"type":"array","items":{"discriminator":{"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/fieldResults/text"},{"$ref":"#/components/schemas/fieldResults/number"},{"$ref":"#/components/schemas/fieldResults/date"},{"$ref":"#/components/schemas/fieldResults/time"},{"$ref":"#/components/schemas/fieldResults/image"},{"$ref":"#/components/schemas/fieldResults/file"},{"$ref":"#/components/schemas/fieldResults/option"},{"$ref":"#/components/schemas/fieldResults/pin"},{"$ref":"#/components/schemas/fieldResults/qr"}]}}}}},"types":{"description":"Asset types represented by the assets on this page","allOf":[{"$ref":"#/components/schemas/propertyassets/types"}]}}}}}},"404":{"content":{"application/json":{"schema":{"oneOf":[{"title":"AssessmentNotFound","type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}}}]}}}}}}}}}
```
## 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"}}}]}}}}}}}}}
```