Assessment administration API

These endpoints manage what surrounds an assessment: the plans new assessments start from, the triggers that open reassessments, assessment SLAs and missing documents, risk results, evals in bulk, reviews, follow-ups to vendors, vendor SLAs, scales, and monitoring records. Each response uses the same shape the Coverbase dashboard reads. All endpoints are org-scoped to the API key. See API conventions for shared behavior. List endpoints take limit (1 to 200, default 50) and offset (default 0) and return items, total, limit and offset. None of these endpoints honor Idempotency-Key.

​

Errors

Every error body has a detail object with a code and a message.

​

Assessment plans

An assessment plan is the template a new assessment starts from: its control sets, questionnaires, document collection mode, reviewer and naming.

​

List plans

​

Create a plan

Returns 201 Created with the plan. The body also accepts description, risk_type, questionnaire_fill_mode, portal_due_days, assessment_name_format, control_set_rules, portal_template_id, doc_collection_settings, follow_up_settings, irq_review_questionnaire_id, irq_review_due_days and recheck_unresolved_controls, with the same meaning as in the dashboard. An API key cannot set summary_instructions.

​

Get, update and set the default

GET /v1/assessment-plans/{assessment_plan_id} returns one plan. PATCH takes the same fields as create. An omitted field keeps its value, and an explicit null clears a clearable field. A list replaces the plan’s control sets or questionnaires. To make a plan the org default, send PUT /v1/assessment-plans/{assessment_plan_id}/default with {"is_default": true}. Send false to stop it being the default.

​

Approval options

GET /v1/approval-options lists the outcomes a reviewer picks from when completing an assessment. Set include_archived=true to include archived options. To add an option, send POST /v1/approval-options with label, color and icon. PATCH /v1/approval-options/{approval_option_id} changes any of the three. Archiving an option is not available to API keys.

​

Reassessment triggers

A reassessment trigger opens a draft reassessment when a radar event matches its rules and vendor scope.

​

Create a trigger

The body also accepts description, assignee_id, applies_to_all_vendors, scope_vendor_ids, scope_tag_ids, scope_tiers, notify_user_ids, ai_instruction and rules.

​

List, get and update

GET /v1/reassessment-triggers lists triggers (include_archived includes archived ones). GET /v1/reassessment-triggers/{trigger_id} returns one. PATCH updates it: an omitted field keeps its value, and null clears description, assignee_id, scope_tag_ids, scope_tiers, ai_instruction or rules.

​

Assessment actions and reads

​

Clone an assessment

POST /v1/assessments/{assessment_id}/clone copies an assessment with its scope and documents and starts the copy’s AI run. Returns 201 Created with the new id, name, vendor_id and run_started.

​

Resume an assessment

POST /v1/assessments/{assessment_id}/resume restarts the assessment’s AI run from its latest step and closes an open vendor portal first. Returns 202 Accepted. It returns 409 with assessment_run_active while a run is already going, and 400 with assessment_no_control_source when the assessment has nothing to evaluate.

​

Regenerate the summary

POST /v1/assessments/{assessment_id}/rerun-summary regenerates the AI summary from the current evals. Add risk_domain_id as a query parameter to regenerate only that risk domain’s summary. Send {"expected_summary_revision": <n>} with the revision you last read: when the summary changed before or during generation, the call returns 409 with summary_conflict and nothing is saved. The response has the assessment id and its current summary_revision.

​

Rerun failed evals

POST /v1/assessments/{assessment_id}/rerun-failed-evals reruns every eval that failed and clears the run errors. Returns 202 Accepted.

​

SLA

GET /v1/assessments/{assessment_id}/sla returns each SLA stage’s target, elapsed time and status, overall and per risk domain. To override targets or measured response times, send PATCH /v1/assessments/{assessment_id}/sla. Values are in days. An omitted field keeps its value, and null clears the override.

​

Missing documents

To record why a requested document is not provided, send PUT /v1/assessments/{assessment_id}/missing-documents/{document_type} with a reason. document_type is a document type slug, for example soc2_type2. DELETE on the same path removes the reason and returns 204 No Content. The PUT returns 403 with missing_document_reasons_disabled when your organization turned the feature off, and 404 with document_type_not_requested when the assessment does not ask for that document.

​

Risk reads

​

Evals in bulk

Each endpoint takes ids, a non-empty list of eval IDs, and returns the IDs it changed and the IDs it skipped. An eval a person already reviewed is skipped unless include_reviewed is true.

​

Correct an eval’s answer

To fix the vendor answer an eval scored, send POST /v1/evals/{eval_id}/correct-response with the correct option. Coverbase records the answer on the assessment and re-evaluates the eval and the evals that depend on its answer. The response has the eval id and its corrected response. The call returns 404 with eval_not_found for an unknown eval, and 409 with eval_correction_rejected when the eval cannot take the correction, for example because it is archived.

​

Rerun an eval

To preview a fresh AI evaluation of one eval, send POST /v1/evals/{eval_id}/rerun. You can pass guidance, expectation or question to try instead of the control’s. The call returns 202 with a job_id and job_status set to pending, or 404 with eval_not_found when the eval cannot be rerun. Poll GET /v1/evals/{eval_id}/rerun/{job_id} until job_status is completed or failed. A completed job has the proposed title, analysis, issue_category, is_issue, score and response. Citations to records you cannot read are left out. A failed job has job_error. An unknown job returns 404 with eval_rerun_job_not_found. The rerun changes nothing on the eval. Applying its result rewrites the verdict, so a person does that in Coverbase.

​

Reviews

GET /v1/reviews lists reviews (sign-offs). Filter with assessment_id, risk_domain_id, assignee_id or contract_id, and set include_archived=true to include archived reviews. GET /v1/reviews/{review_id} returns one review.

​

Follow-ups

A follow-up is a question to the vendor about one eval. Follow-ups are sent in follow-up rounds.

​

Create a follow-up

Returns 201 Created. The follow-up joins the assessment’s current round. The body also accepts additional_instructions and use_control_question.

​

List, get and update

GET /v1/follow-ups lists follow-ups (filter with assessment_id or eval_id). GET /v1/follow-ups/{follow_up_id} returns one with the vendor’s response. PATCH changes question, additional_instructions, required_document_types or use_control_question. An API key cannot change is_archived. To create and edit many follow-ups in one all-or-nothing save, send POST /v1/follow-ups/bulk with items (1 to 500). An item with an id updates that follow-up, and an item without one creates a follow-up. The response lists the saved follow-ups. GET /v1/follow-up-rounds lists rounds (filter with assessment_id), and GET /v1/follow-up-rounds/{round_id} returns one round with its follow-ups. To get the assessment’s current unsent round, creating it when there is none, send POST /v1/follow-up-rounds/current with assessment_id. PATCH /v1/follow-up-rounds/{round_id} sets follow_up_ids (replacing the set), instructions or status. A sent round cannot go back to unsent or be emptied; the call returns 422 with invalid_follow_up_round.

​

Send a round

To send a round to the vendor, send POST /v1/follow-up-rounds/{round_id}/send. Coverbase puts the round’s follow-ups in a questionnaire on the assessment’s vendor portal and marks the round sent. The response has the questionnaire_id, assessment_id and portal_id. If the round was sent but the invitation could not be queued, the call still succeeds and error_message says so. The call returns 404 with follow_up_round_not_found for an unknown round, and 422 with follow_up_round_not_sendable when the round cannot be sent, for example because it has no follow-ups or its responses are already in.

​

Vendor SLAs

To track an SLA on a vendor, send POST /v1/slas with vendor_id and name. The body also accepts status, service_id, risk_domain_id, description, metric, target, unit, frequency, current_value, last_measured_at, due_date, assignee_id, measurement_source, radar_origin_id and component_key. A status-page SLA takes its first measurement right away. Returns 201 Created. PATCH /v1/slas/{sla_id} changes the same fields. An omitted field keeps its value, and an explicit null clears a clearable field. An API key cannot set is_archived. GET /v1/slas lists service level agreements tracked on vendors. Filter with vendor_id, service_id or status (on_track, at_risk, breached, met), and set include_archived=true to include archived ones. GET /v1/slas/{sla_id} returns one SLA, and GET /v1/slas/{sla_id}/measurements returns the measurement periods of a status-page SLA, newest first.

​

Scales

GET /v1/scales lists control scales with their levels (include_archived includes archived ones). GET /v1/scales/{scale_id} returns one scale. POST /v1/scales creates a control scale from name, description and levels (each with name, criteria, value, color and raise_issue) and returns 201 Created. PATCH /v1/scales/{scale_id} renames it, reorders its levels with level_ids, or sets is_default. To drop a level from a risk scale, send remap to move what used it to another level. An API key cannot send is_archived, so a person retires and restores scales. POST /v1/scales/{scale_id}/levels adds a level and returns 201 Created. PATCH /v1/scales/{scale_id}/levels/{level_id} edits one; send residual_risk_remaining as null to go back to the derived share. The assessment rating scale changes only through its own endpoints and returns 422 assessment_scale here. POST /v1/scales/{scale_id}/apply puts controls on the scale. Send controls_by_control_set, a map from control set ID to control IDs. The response returns the controls now on the scale. Every scale write needs a key created by a person whose role holds org_settings:update:org. An unknown scale returns 404 scale_not_found, and an unknown level 404 scale_level_not_found.

​

Monitoring records

A monitoring record collects what monitoring observed about a vendor between two assessments. These endpoints return the record’s id, vendor_id, status, verdict and qualifying_count. To add an event you observed, send POST /v1/monitoring-records/{record_id}/entries. The body also accepts severity and note. To change how an entry counts, send POST /v1/monitoring-records/{record_id}/entries/{entry_id}/disposition with disposition set to counts, informational or null (back to the policy). An API key cannot send waived. To re-sync a vendor’s record now, send POST /v1/vendors/{vendor_id}/monitoring-record/refresh. It returns null when the vendor has no completed assessment to monitor from. To read records in full, send POST /v1/monitoring-records/query. It filters by status (default open), verdicts, vendor_ids, closes_before, closes_after and search, sorts with sort and descending, and pages with limit and offset. It returns items, total and verdict_counts. GET /v1/monitoring-records/{record_id} returns one record with its entries, and GET /v1/vendors/{vendor_id}/monitoring-records returns the vendor’s chain of records and the open one in current. GET /v1/monitoring-policy returns the policy records are scored under. PUT /v1/monitoring-policy replaces it, and open records use it from their next sync. Replacing it needs a key created by a person whose role holds org_settings:update:org; a policy that breaks a rule returns 422 invalid_monitoring_policy. When monitoring records are not enabled for your organization, these routes return 404 not_enabled.

​

Background AI jobs

A model call from the API runs in the background. The route that starts one returns 202 Accepted with a job: id, kind, status (pending, completed or failed), created_at, started_at, completed_at, error and result. Poll GET /v1/ai-jobs/{job_id} until status leaves pending. Only the key that started a job reads it back, and it needs the permission that started it.

• POST /v1/assessments/{assessment_id}/follow-up-suggestions asks for a follow-up question or the documents to request for each eval. Send target (question or required_document_types) and up to 200 eval_ids. The result lists one item per eval. Nothing is saved.
• POST /v1/assessments/{assessment_id}/template-filler-jobs runs the report template agent on one prompt, with dates in timezone. The result’s result is the text. Nothing is saved.
• POST /v1/evals/{eval_id}/analysis-summary writes a new short summary of the eval’s analysis and saves it when the job completes. The job fails if the analysis changed while the summary was written.

POST /v1/evals/bulk-correct-response keeps each eval’s current answer and evaluates it again. Send up to 500 eval_ids. It returns 202 Accepted with queued_eval_ids.

​

Assessment exports

Every export runs in the background and returns 202 Accepted with an export: id, status, progress and file_name. Poll GET /v1/assessment-exports/{export_id}. Once status is complete, the response carries a presigned download_url valid for expires_in seconds. Follow it with a plain GET and no auth header. The response is sent with Cache-Control: no-store.

• POST /v1/assessments/{assessment_id}/exports/pdf builds the PDF report. It takes export_filename, export_mode (standard or detailed), timezone and the include_* switches the dashboard offers. Snippet images citing a record your key cannot read are left out.
• POST /v1/assessments/{assessment_id}/exports/word fills one of your Word report templates. Send export_filename, template_id and timezone.
• POST /v1/assessment-exports exports the assessments a filter selects to a workbook named file_name. Omit filter for every assessment.
• POST /v1/assessment-exports/evals exports every result between start_date and end_date.
• POST /v1/assessment-exports/portfolio builds the portfolio PDF over the slice request selects. It needs the new PDF report, and returns 404 with not_enabled without it.

​

Library documents

To copy documents from Coverbase’s library for the vendor onto the vendor and attach them to an assessment, send POST /v1/assessments/{assessment_id}/library-documents with up to 100 entity_document_ids. A file the assessment already has, or one that cannot be copied, is listed in skipped_entity_documents with the reason.

​

Trust center

POST /v1/assessments/{assessment_id}/trust-center-runs sends Coverbase’s agent to the vendor’s trust center to collect the assessment’s documents. This contacts the vendor: the agent visits the vendor’s trust center. From the API it never submits an access request form and never accepts an NDA or terms. A person does that from Coverbase. Omit requested_document_names to ask for the documents the assessment still needs, or set document_retrieval_scope to retrieve_everything. An assessment with a run under way returns that run. Read the runs with GET /v1/assessments/{assessment_id}/trust-center-runs and what the agent did on one with GET .../trust-center-runs/{run_id}/events. GET /v1/assessments/{assessment_id}/trust-center-status says where collection stands, and GET .../trust-center-request-identity says who an access request would come from. GET /v1/trust-center-access-requests/{access_request_id} returns an access request and its decision.

​

Claim checks

A claim check tests each answer on a submission against the vendor’s evidence. These routes need claim checks to be enabled for your organization, and return 404 with not_found otherwise.

• GET /v1/questionnaire-responses/{response_id}/claim-checks returns the latest run and every answer’s verdict with its citations.
• POST .../claim-checks/run checks the submission in the background, or only the question_ids you send. A run already queued or running is returned instead.
• POST .../claim-checks/cancel stops a run that has not started. It returns 409 with claim_check_not_queued when no run is waiting.
• POST .../claim-checks/raise-issues raises one issue per answer in question_ids.
• POST .../claim-checks/ask-vendor asks the vendor about each answer in question_ids with your message. This contacts the vendor: the message is posted on the supplier request thread the vendor reads.

​

Assessments

These routes run the same logic as the dashboard and return its shapes.

• POST /v1/assessments/query filters, sorts and pages assessments with the dashboard’s filter language.
• POST /v1/assessments/bulk starts one assessment per vendor in vendor_service_ids.
• PATCH /v1/assessments/{assessment_id} updates an assessment. An API key cannot set is_archived, status_id, recommendation or the approval option, or move the assessment to complete.
• POST /v1/assessments/{assessment_id}/complete completes an assessment with its outcome. It needs a person’s key.
• POST /v1/assessments/{assessment_id}/portal opens a vendor portal with the questionnaire_ids you send. Nothing is sent to the vendor.
• GET .../run-status, GET .../evidence-sufficiency, GET .../control-set-compliance and GET .../residual-step-down-holds read the assessment. GET /v1/assessment-collection-stage-stats says how long each collection stage takes in your org.
• PUT .../summary-instructions chooses the saved summary instructions the summary uses.
• GET .../irq-review reads the inherent risk check a reassessment opened with, and POST .../irq-review/skip starts the assessment without it.
• PUT .../vendor-rating/{control_set_id} sets or clears an analyst level on the vendor rating.

POST /v1/assessment-plans/document-requirements-preview and POST /v1/assessment-plans/{assessment_plan_id}/document-requirements show the documents a plan’s collection would pursue.

​

Properties fields, doc evals and evals

/v1/assessment-properties-fields lists, adds (POST), changes (PATCH) and removes (DELETE) the fields the assessment properties panel shows. Removing one needs a person’s key. GET /v1/doc-evals and GET /v1/doc-evals/{doc_eval_id} read document evaluations, and PATCH corrects one. POST /v1/evals/query filters evals, GET /v1/evals/{eval_id} reads one, and GET /v1/evals/{eval_id}/response-dependencies lists the evals that depend on its answer. GET /v1/evals/override-report takes start_ts and end_ts and reports how often reviewers overturned each control.

​

Follow-up workbooks, reviews and summary instructions

GET /v1/follow-up-rounds/{round_id}/email-recipients returns who a round’s invitation would go to. POST /v1/follow-up-rounds/{round_id}/import takes a filled-in workbook as a multipart file and lands it as if the vendor had answered in the portal. Send dry_run=true to preview the rows. A preview writes nothing. POST /v1/reviews requests a review of an assessment. PATCH /v1/reviews/{review_id} renames, rewords or reassigns it. Recording its decision needs a person’s key. GET /v1/summary-instructions/default returns Coverbase’s built-in summary instructions. GET /v1/summary-instructions/{prompt_id}/revisions lists earlier revisions. POST /v1/summary-instructions/{prompt_id}/rename renames them, with the expected_name you read. Renaming needs a key created by a person whose role holds org_settings:update:org.

​

Assessment rating scale

GET /v1/assessment-rating-scale returns the scale, or null when assessments take their label from control scales. GET .../suggested-levels proposes levels from the default control scale. PUT .../levels creates the scale or replaces its levels, and DELETE turns it off. Both need a key created by a person whose role holds org_settings:update:org, and turning it off needs a person’s key.

​

Coverbase AI conversations

POST /v1/interrogate-sessions opens a conversation about an assessment, a vendor, a radar event or your org, with subject_type and subject_id. GET /v1/interrogate-sessions?subject_type=...&subject_id=... lists conversations about one subject, and GET /v1/interrogate-sessions/{session_id} returns one with every message. To ask a question, send POST /v1/interrogate-sessions/{session_id}/messages with content. It returns 202 Accepted with a job. Poll GET /v1/ai-jobs/{job_id}: the result holds the answer and any tool_proposals. The answer is also saved on the conversation. The API never applies a proposed change; a person applies it in Coverbase.