Skip to main content
For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
You use these endpoints to launch Zero Touch Assessments with an API key, read and rank their results, review them, and change how they score. A Zero Touch Assessment is a triage run built from open-source research and the documents Coverbase already holds, with no document request, no questionnaire and no vendor contact. It produces one 0 to 100 Zero Touch Score, so you can rank a portfolio before you spend review effort. For the concepts behind the score, see Zero Touch Assessments.
Every endpoint below is behind the zero-touch-assessments module. If the module is not enabled for your organization, every route returns 404 with code zero_touch_not_enabled. Contact your Coverbase representative to have it turned on.
Every endpoint takes an ak_ API key or a signed-in user’s token, and every endpoint is scoped to your organization. Errors return {"detail": {"code": "...", "message": "..."}}. See API conventions for IDs, timestamps, and authentication. The older /v1/zero_touch_assessment paths remain for the Coverbase dashboard and need a signed-in user, so an API key gets 401 there.

Permissions

Each endpoint checks the same permission the dashboard checks. Where an endpoint says it needs update or read access to the assessment, a caller with the organization-wide permission (assessment:update:org or assessment:read:org) reaches every run, and a caller with the assigned permission reaches only the runs assigned to them.
An API key cannot archive a run or record a run’s outcome. A review or bulk review with action set to archived, or with an approval_option_id, returns 403 with code api_key_not_allowed for an API key. A signed-in user must make those decisions.

Launch a run

POST
POST /v1/zero-touch-assessments
Starts a Zero Touch Assessment for one vendor. The run works in the background. Needs assessment:create:org.
string
required
The vendor ID (cbvndr_...) to assess.
string[]
The vendor’s services the run is about. Omit to assess the vendor as a whole.
string[]
Zero Touch eligible control sets the run evaluates. Omit to evaluate every eligible set.
string
A correction in plain language, up to 2000 characters, applied to the vendor before the run starts. Use it when the vendor record points at the wrong company or website. Research reads the vendor’s website at launch, so a correction made afterwards does not change what the run read.
string[]
Parts of the run to leave out, from controls, security, financial_health, registration, people, reputation and licenses. At least one section must run. Defaults to none.
boolean
Whether the vendor’s research is refreshed before the run grades. false grades on the research already on file. Defaults to true.
string[]
The vendor’s own documents the run judges its controls on, from List documents a run can use. If you omit both document lists, the run uses every document on offer. Pass [] for both to use none. Naming any document needs Documents Evidence in ZTA.
string[]
Coverbase library documents the run uses. They are copied into the vendor’s documents before the run reads them.
To change which template every later run evaluates, use Choose a template before you launch.

Launch in bulk

POST
POST /v1/zero-touch-assessments/bulk
Starts a run for each of many vendors in one call. Vendor IDs are deduplicated. Needs assessment:create:org.
string[]
Vendor IDs to assess, up to 200. Name at least one vendor or one prospect.
object[]
Up to 50 companies that are not yet vendors, each {"name": "...", "website": "..."} (website is optional). Each becomes a vendor with the Prospect status, or reuses your vendor on the same website, and is launched with the batch. Needs the TPRM expansion (otherwise 404, code not_enabled) and vendor:create:org.
string[]
Zero Touch eligible control sets every run evaluates. Omit to evaluate every eligible set.
string[]
Sections every run leaves out, from the same list as a single launch.
boolean
Applied to every run in the batch. Defaults to true.
boolean
Whether each run uses every document on offer for its vendor. false uses none. Ignored without Documents Evidence in ZTA. Defaults to true.
object[]
Per-vendor picks, each {"vendor_id": "...", "vendor_document_ids": [...], "library_document_ids": [...]}. A vendor named here uses exactly those documents, whatever use_existing_documents says. Each vendor_id must appear in vendor_ids, and only once. Needs Documents Evidence in ZTA (otherwise 404, code documents_evidence_not_enabled).
A partial success returns 201. The response separates the two outcomes:
object[]
Run summaries for the vendors that launched.
object[]
One entry per vendor that could not launch, each with vendor_id and error.
One archived or unknown vendor in a batch of forty does not stop the other thirty-nine. Always read failed, because a 201 does not mean every vendor launched.

Read a run

GET
GET /v1/zero-touch-assessments/{assessment_id}
Returns the single-page result: who the vendor is, what turned up against its name, the composite, the components behind it, control set coverage, controls grouped by section, open issues with their evidence, the briefing, what to ask the vendor for, and every source cited. A run that has not finished is scored on the fly. A full assessment ID returns 404 (zero_touch_assessment_not_found). Needs read access to the assessment.
integer
An earlier version of a revised result to read instead of the current one. A version the run does not have returns 404 (version_not_found).
string
The run’s status. A run held for its automated review reads automated_review, and its result fields are empty until the review reports.
string
pending, approved or escalated.
object | null
The researched company profile: company_name, url, description, industry, use_case, services, hq_location, and confidence, which is how sure the run is it profiled the right company. null until the research completes, which happens shortly after launch and separately from the controls.
string | null
critical, high, moderate, low or minimal, with risk_tier_confidence, a one-line risk_tier_reasoning and the full risk_tier_detailed_reasoning.
This is its own scale, not your organization’s risk levels. Those are calibrated against a completed questionnaire, and this one is judged from public evidence. Do not map one onto the other.
number | null
The Zero Touch Score, 0 to 100, higher is healthier. null when nothing has resolved yet.
object[]
One entry per component (controls, financial_health, security, registration, people), each with status (scored, unavailable or disabled), its own score, the configured_weight set for your organization, and the weight it carried.
object | null
What the run found against the vendor’s name, from adverse media, open watchlist matches and the run’s own ZT-REP-* controls. Carries an overall standing, a one-line headline, finding_count and material_count, a dimensions array, and a findings array. null on a run scored before this section existed, which means the run never assembled one, not that the vendor is clear.
object[]
One entry per dimension (media_sentiment, litigation, regulatory, executive_conduct, association), each with its label, its own standing, finding_count, material_count and a detail line.
object[]
One entry per reputational matter, material first and then by severity. Each carries the origin that raised it (adverse_media, screening, control), the dimension it is filed under, a headline and summary, the subject it attaches to (null for the company itself), a severity, an outcome, publisher, published_at, jurisdiction, source_urls, is_disputed and is_resolved.
A dimension nothing searched reads not_screened, never clear. The four standings are adverse, watch, clear and not_screened. clear means something searched and found nothing. not_screened means nothing searched, and it carries no information about the vendor. coverage_note names every unscreened dimension. Do not treat an empty findings array as a clean record without reading dimensions.
object[]
Every place the run drew evidence from, grouped by kind: web, registry, infrastructure, document.
object[]
The evaluated controls grouped by section. Each control carries its eval_id, code, title, outcome (validated, partially_validated, not_validated, not_enough_information or not_applicable), is_issue, is_resolved, review_notes, source_urls and finding_ids. Use eval_id to triage a control.
object[]
What to ask the vendor for, one line each, with the key you edit it by, text, original_text, status (open or dismissed) and is_edited.
object | null
For a revised result, the version_number you are reading, the current_version_number, and the analyst provenance and rerun flags. null until the result is first revised.
A component with no data is excluded from the composite, never counted as zero. Weights renormalise over whatever resolved, which is why weight and configured_weight differ. A vendor scored on one component is not comparable to a vendor scored on three, so read components before you rank on composite_score.

Promote a prospect

POST
POST /v1/vendors/{vendor_id}/promote-prospect
Adds a prospect to your portfolio and moves it to the Onboarding status. A prospect is a company you launched a run on before it was a vendor, for example through prospects on a bulk launch. Returns the vendor, in the same shape as GET /v1/vendors/{vendor_id}. Needs the TPRM expansion (otherwise 404, code not_enabled) and vendor:update:org.

Rank a portfolio

GET
GET /v1/zero-touch-assessments/leaderboard
Returns one row per vendor, at its most recent run, ranked by composite score, highest first. This is also how you list runs: a run is an assessment, and the leaderboard is the list of each vendor’s latest run.
integer
Rows per page, 1 to 200. Defaults to 50.
integer
Rows to skip. Defaults to 0.
Only vendors whose name matches this text.
The response carries items (run summaries), total, limit and offset. The ranking covers every vendor before the page is cut, so paging gives a true global ranking. Unscored runs sort last, not as zero.

Read the module counters

GET
GET /v1/zero-touch-assessments/pulse
Returns total_runs, recent_runs (runs created in the last 30 days), vendors_covered and issues_surfaced. Every counter is an exact count.

Read and set the scoring configuration

GET
GET /v1/zero-touch-assessments/config
Returns whether the module can run (is_ready), the assessment_plan_id, the control sets in scope with their control_count, and the current configuration under scoring. The first read provisions the shipped templates for an organization that has never used the module.
PUT
PUT /v1/zero-touch-assessments/config
Changes what counts toward the score and where the score goes. Omitted fields keep their value. Returns the configuration. Needs assessment:create:org.
boolean
Whether the Financial Health Score is a component.
boolean
Whether the outside-in security rating is a component.
boolean
Whether corporate registration standing is a component.
boolean
Whether the leadership dossier is a component.
integer
Relative weight of the control evaluation, 0 to 100. Weights are relative, not percentages, and they renormalise over whichever components resolve.
integer
Relative weight of the financial health component, 0 to 100.
integer
Relative weight of the security component, 0 to 100.
integer
Relative weight of the registration component, 0 to 100.
integer
Relative weight of the people component, 0 to 100.
The people component deducts for adverse-media findings only when screening ran. When it did not, the component scores leadership visibility alone and says so in its qualifier. Do not read its score as evidence of a clean record. See People Intelligence.
string
Where a completed run writes its score: none, vendor_inherent, vendor_residual, service_inherent, or service_residual.
Only the axis you choose is written, so a Zero Touch run never overwrites an inherent score your team set from an intake questionnaire. A vendor-scoped run configured for a service target writes nothing and reports why in result.push_skipped_reason.
boolean
Whether a completed run writes its risk tier onto vendor inherent risk. Off by default.
The tier is a triage read from public evidence, so an organization that has not asked for it never finds a vendor’s inherent risk moved by one. Even when enabled, the push stands down if score_target is already vendor_inherent, because two writers on one field would let run order decide the vendor’s risk. It reports why in result.risk_tier_push_skipped_reason.
boolean
Whether a finished run is checked a second time against the vendor’s own pages, with the supported changes applied as a new version of the result. On by default.
object
Replaces your organization’s financial stability methodology: the bands for customer_concentration, current_ratio, debt_to_worth and ebitda_coverage, their bases, require_audit_for_low, show_diligence_estimates, combination, considerations_enabled and sector_profiles. The GET returns the methodology in use and financial_stability_policy_is_default.
boolean
Set to true to return to the FSA standard preset instead of sending a policy.
object
Maps a Zero Touch risk tier (critical, high, moderate, low, minimal) to a risk level ID on your organization’s risk scale. Runs label the tier with the mapped level, and the tier push writes it. An explicit null clears the map, back to fixed scores. Written only for an organization with the TPRM expansion.

List and choose templates

GET
GET /v1/zero-touch-assessments/templates
Returns the shipped templates under data, each with key, name, description, control_count, domains, is_default, control_set_id and is_added, plus active_template_key, the one template your runs currently evaluate. active_template_key is null when your organization runs a control set of its own, or when more than one shipped template is designated.
POST
POST /v1/zero-touch-assessments/template
string
required
The shipped template future runs evaluate.
Points future runs at that template, and only that one. It re-designates only control sets this module provisioned, so a set designated for you by Coverbase is never changed. Returns the same body as the GET. Needs control_set:create:org, which API keys hold.
This is an organization setting. It changes what every later run evaluates, including runs launched from the dashboard.

Add templates from the library

POST
POST /v1/zero-touch-assessments/library
string[]
required
One to 20 shipped template keys.
Adds each template as a Zero Touch eligible control set, alongside any already designated. A template your organization already holds is reused, and brought back if archived. Returns control_set_ids. An unknown key returns 400 (unknown_template). Needs control_set:create:org.

List documents a run can use

GET
GET /v1/zero-touch-assessments/documents
string
required
The vendor to look up.
Returns documents, the existing documents a run for this vendor can use, the vendor’s own first. Each carries id, source (vendor_document or library_document), name, document_type, document_type_name, dated_at and expires_at. Needs read access to the vendor. An unknown vendor returns 404 (vendor_not_found).
POST
POST /v1/zero-touch-assessments/documents/summary
string[]
required
One to 200 vendors to check.
Returns vendors_with_documents and vendors, the vendors among these that have documents a run can use, each with its documents. Vendors you cannot read are left out. Both endpoints need Documents Evidence in ZTA. Without it they return 404 (documents_evidence_not_enabled).

Re-score a run

POST
POST /v1/zero-touch-assessments/{assessment_id}/rescore
Recomputes the composite against today’s inputs and re-applies the configured score push, without re-running the controls. Use it when the financial or security inputs have refreshed, or after you change the scoring configuration. Returns the run. A run still working, or held for its automated review, returns 409 (run_not_finished), because rescoring it would publish a partial score. Needs assessment:create:org.

Run the automated review again

POST
POST /v1/zero-touch-assessments/{assessment_id}/auto-review
Runs the automated review of a finished run again. The result is held back until the new review reports, as when the run first completed. A run that cannot be reviewed returns 409 (auto_review_not_runnable). Needs assessment:create:org.

Re-source a run’s vendor profile

POST
POST /v1/zero-touch-assessments/{assessment_id}/reprofile
Re-researches the company behind the run and replaces the profile on it. This is separate from re-scoring because a correction that repoints a run at the right company leaves the score valid while the profile still describes another company. Re-scoring carries an existing profile forward, so this is the only call that refreshes it. Returns the run. Needs update access to the assessment.

Review a run

POST
POST /v1/zero-touch-assessments/{assessment_id}/review
Records a decision against a run without changing what it was built on. Returns the review event. Needs update access to the assessment.
string
required
approved, escalated, archived, or note. Archiving takes the run out of the working set and needs assessment:archive:org.
string
Free text, up to 4000 characters.
string
Approvals only. A vendor status (cbst_...) to settle the vendor on. Needs update access to the vendor.
string
Approvals only. Your organization’s approval option, recorded as the run’s outcome. Needs assessment:approve:org.
string
Escalations only. The full assessment of the run’s vendor this run escalated into. Needs update access to that assessment.
Escalating records the judgement. It does not launch a full assessment. A decision the run cannot take, for example an outcome on a run that is still working, returns 422 (invalid_review). An API key that archives or sends an approval_option_id gets 403 (api_key_not_allowed).

Review runs in bulk

POST
POST /v1/zero-touch-assessments/bulk-review
Records one decision against each run in a batch, with one review event per run. Needs assessment:update:org.
string[]
required
One to 500 run IDs.
string
required
approved, escalated, archived, or note. Archiving needs assessment:archive:org.
string
Free text written on every run, up to 4000 characters.
string
Approvals only. The outcome every run records. Needs assessment:approve:org. Any other action with an outcome returns 422 (invalid_review).
Returns reviewed_ids and skipped_ids. An ID that is not a Zero Touch run, or a run that cannot take the outcome because it is still working or held for its review, is skipped. An API key that archives or sends an approval_option_id gets 403 (api_key_not_allowed).

Triage controls

POST
POST /v1/zero-touch-assessments/{assessment_id}/triage
Confirms or dismisses what the run concluded about one or more controls, or leaves a note on them. The verdict is written to the evals, so the assessment page, the export and any finding raised from the control read the same fact. Needs update access to the assessment.
string[]
required
One to 200 eval IDs from the run’s sections.
string
confirmed keeps an issue standing or reopens a dismissed one. dismissed marks the issue resolved.
string
Review notes written on each eval, up to 4000 characters.
Returns updated_ids and skipped_ids. An eval ID that is not on this run is skipped. A request with neither a verdict nor a note returns 400 (empty_triage).

Correct a run’s inputs

POST
POST /v1/zero-touch-assessments/{assessment_id}/correct
string
required
The correction in plain language, 1 to 2000 characters.
Coverbase reads the instruction into a fixed set of correctable fields (the vendor’s website and name), applies them, and re-scores the run. A website correction also queues a refresh of the vendor’s research, because the stored research came from the site you rejected. Returns the re-scored run. Needs update access to the assessment.
An instruction that yields no concrete change still returns 200 and still writes an audit entry with an empty changes array. Read changes to see what moved.

Read the audit trail

GET
GET /v1/zero-touch-assessments/{assessment_id}/audit
Returns every review action on a run, oldest first, as items with total, limit and offset. Needs read access to the assessment.
string
approved, escalated, corrected, rescored, revised, restored, rerun_requested, note, or archived.
string | null
The reviewer’s own words, stored verbatim, for corrected entries.
object[]
One entry per field the action changed, each with field, before and after. Empty for approvals, notes, and corrections that resolved to nothing.
number | null
The Zero Touch Score before and after the action.
The trail is append-only. There is no update or delete endpoint. A Zero Touch Score can be pushed onto a vendor’s risk score, so nobody can rewrite the record of who changed the inputs behind it.

Revise a result from analyst text

To revise a result, you propose analyst text, read the change set it produces, optionally preview a subset, and apply the changes you accept. Every step needs access to the assessment: read access for the reads and the preview, update access for the rest.
POST
POST /v1/zero-touch-assessments/{assessment_id}/revisions
string
required
The analyst’s text, 1 to 20000 characters.
Starts reading the text against the result and returns 202 with the proposal: proposal_id, status (queued, reading, reconciling, ready or failed), parts_done, parts_total and failure_reason. Nothing about the result changes yet.
GET
GET /v1/zero-touch-assessments/{assessment_id}/revisions/{proposal_id}
Returns the proposal’s progress. Once status is ready, proposal carries the summary, the proposed changes (each with an id, section, target, operation, old_value, new_value, rationale, evidence, confidence and derived_from), the rejected changes, the ignored_instructions, and current_scores and proposed_scores with every change accepted.
POST
POST /v1/zero-touch-assessments/{assessment_id}/revisions/{proposal_id}/preview
string[]
The change IDs to score as accepted.
Returns current_scores and proposed_scores for that subset. Writes nothing.
POST
POST /v1/zero-touch-assessments/{assessment_id}/revisions/{proposal_id}/apply
string[]
required
The change IDs to apply. Only IDs are taken: the changes come from the stored, validated proposal.
Applies the accepted changes as a new version of the result and returns the run.

List and restore versions

GET
GET /v1/zero-touch-assessments/{assessment_id}/versions
Returns every version of a revised result, newest first, as items with total, limit and offset. Each version carries version_number, kind, actor, created_at, pasted_text, applied_changes, restored_from_version_number, composite_before, composite_after and is_current. The list is empty until an analyst first revises the result. Needs read access to the assessment.
POST
POST /v1/zero-touch-assessments/{assessment_id}/versions/{version_number}/restore
Makes an earlier version current again. It writes a new version and keeps the history between the two. Returns the run. A version the run does not have returns 404 (version_not_found). Needs update access to the assessment.

Rerun flagged stages

POST
POST /v1/zero-touch-assessments/{assessment_id}/rerun
string[]
required
Stages the current revision flagged, from registration, sanctions, people, financial and security.
Reruns those pipeline stages against the corrected company. When the stages include registration, the first legal entity the revision recorded becomes the registry search name. The rerun lands on the vendor’s shared research, so rescore the run afterwards. Returns dispatched_stages and legal_name. A stage the revision did not flag, a stage left out of the run, or a vendor with no research record returns 422 (rerun_refused, with stages). Needs update access to the assessment.

Edit what to ask the vendor for

PATCH
PATCH /v1/zero-touch-assessments/{assessment_id}/vendor-requests
object[]
required
One to 200 edits, each {"key": "...", "text": "...", "status": "open", "is_deleted": false}. key comes from the run’s vendor_requests. Every other field is optional and a field you leave out keeps its value. status is open or dismissed.
Returns the run’s lines as they now read, as items with total, limit and offset. A key the run does not list returns 422 (unknown_vendor_requests, with keys) and nothing is written. Needs update access to the assessment.

Via MCP

Agents reach the same operations through the Coverbase MCP server. Reads go through query_assessments:
Writes go through mutate and need a write-scoped token and confirm: true in data: Every read and write is scoped to the authenticated user’s organization and checks the same permissions as the endpoints above. See the MCP overview.