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.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.
Launch a run
Starts a Zero Touch Assessment for one vendor. The run works in the background. Needsassessment:create:org.
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.
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.Whether the vendor’s research is refreshed before the run grades.
false grades on the research already on file. Defaults to true.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.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
Starts a run for each of many vendors in one call. Vendor IDs are deduplicated. Needsassessment:create:org.
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.Whether each run uses every document on offer for its vendor.
false uses none. Ignored without Documents Evidence in ZTA. Defaults to true.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).201. The response separates the two outcomes:
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
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 returns404 (zero_touch_assessment_not_found). Needs read access to the assessment.
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).The run’s status. A run held for its automated review reads
automated_review, and its result fields are empty until the review reports.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.critical, high, moderate, low or minimal, with risk_tier_confidence, a one-line risk_tier_reasoning and the full risk_tier_detailed_reasoning.The Zero Touch Score, 0 to 100, higher is healthier.
null when nothing has resolved yet.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.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.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.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.Every place the run drew evidence from, grouped by
kind: web, registry, infrastructure, document.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.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.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.Promote a 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 throughprospects 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
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. The response carriesitems (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
Returnstotal_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
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.
Changes what counts toward the score and where the score goes. Omitted fields keep their value. Returns the configuration. Needs assessment:create:org.
Relative weight of the control evaluation, 0 to 100. Weights are relative, not percentages, and they renormalise over whichever components resolve.
Where a completed run writes its score:
none, vendor_inherent, vendor_residual, service_inherent, or service_residual.result.push_skipped_reason.
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.
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.
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.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
Returns the shipped templates underdata, 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.
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.
Add templates from the library
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. Returnscontrol_set_ids. An unknown key returns 400 (unknown_template). Needs control_set:create:org.
List documents a run can use
Returnsdocuments, 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).
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
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, returns409 (run_not_finished), because rescoring it would publish a partial score. Needs assessment:create:org.
Run the automated review again
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 returns409 (auto_review_not_runnable). Needs assessment:create:org.
Re-source a run’s vendor profile
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
Records a decision against a run without changing what it was built on. Returns the review event. Needs update access to the assessment.approved, escalated, archived, or note. Archiving takes the run out of the working set and needs assessment:archive:org.Approvals only. A vendor status (
cbst_...) to settle the vendor on. Needs update access to the vendor.Approvals only. Your organization’s approval option, recorded as the run’s outcome. Needs
assessment:approve:org.Escalations only. The full assessment of the run’s vendor this run escalated into. Needs update access to that assessment.
422 (invalid_review). An API key that archives or sends an approval_option_id gets 403 (api_key_not_allowed).
Review runs in bulk
Records one decision against each run in a batch, with one review event per run. Needsassessment:update:org.
Approvals only. The outcome every run records. Needs
assessment:approve:org. Any other action with an outcome returns 422 (invalid_review).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
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.confirmed keeps an issue standing or reopens a dismissed one. dismissed marks the issue resolved.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
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
Returns every review action on a run, oldest first, asitems with total, limit and offset. Needs read access to the assessment.
approved, escalated, corrected, rescored, revised, restored, rerun_requested, note, or archived.One entry per field the action changed, each with
field, before and after. Empty for approvals, notes, and corrections that resolved to nothing.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. Starts reading the text against the result and returns202 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.
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.
Returns current_scores and proposed_scores for that subset. Writes nothing.
The change IDs to apply. Only IDs are taken: the changes come from the stored, validated proposal.
List and restore versions
Returns every version of a revised result, newest first, asitems 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.
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
Stages the current revision flagged, from
registration, sanctions, people, financial and security.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
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.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 throughquery_assessments:
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.