Monitoring and insights API

These endpoints give you API access to four monitoring features: Inspect schedules (internal controls monitoring), the document insight review queue, dark web monitoring, and the Certificate Vault. All endpoints are scoped to the API key’s organization. See API conventions for shared behavior. List endpoints take limit and offset and return items, total, limit, and offset. Routes that need a dark_web_exposure permission, a role permission, or org_settings:update:org work with a user API key only. Service account keys do not hold those permissions, so use a key created by a person whose role holds them. Each feature has its own gate. When your organization does not have the feature, its endpoints return 404 with one of these codes: When your organization enforces roles and the key lacks the permission, the endpoint returns 403. Some actions stay with a signed-in person. When an API key calls one of them, the endpoint returns 403 with the code api_key_not_allowed. These actions are: archiving or restoring a document insight (one at a time or in bulk), unlinking a custom field from an insight, resetting a dark web playbook, retiring a decision model, deleting an insight group or target, stopping an Inspect schedule, removing a watchlist identifier, marking a certificate verified, archiving a certificate, archiving a rule set, deleting an insight example or value, archiving or restoring an org document, deleting a document insight, rejecting a pending change, creating dark web roles, confirming a dark web setup step, provisioning or deprovisioning an Okta or Entra inspection identity, and rejecting or manually completing an access removal request. API keys never change roles.

​

List Inspect schedules

Returns your recurring Inspect schedules, newest first. A schedule inspects one application against its control sets on a day of the month or at a fixed interval.

​

Response

​

Pause or resume an Inspect schedule

To stop a schedule from starting inspections for a while, pause it. To start it again, resume it. Both return the updated schedule in the same shape as the list items. Pausing a paused schedule changes nothing.

​

Errors

​

List document insight pending changes

Returns the field changes that document insights propose, newest first. An insight with a review-required update policy holds each change here until a person approves or rejects it in Coverbase. API keys cannot approve or reject changes.

​

Response

​

Get the dark web summary

Returns the dark web monitoring rollup: open exposures by severity and category, recent activity, and how many identifiers and vendors you monitor. Vendor exposures follow the key’s vendor read scope.

​

Response

​

List dark web exposures

Returns dark web exposures, worst severity first. Each item masks the identifier it matched. To see the full identifier and evidence, open the exposure in Coverbase.

​

Response

​

List vendor certificates

Returns the vendor certificates in the Certificate Vault, soonest-expiring first.

​

Response

​

List Inspect applications

Returns the applications Inspect monitors, most recently updated first. Each item has id, display_name, auth_method, platform_key, vendor_id, and is_archived.

​

List inspections

Returns Inspect inspections, newest first. Each item has id, target_id, app_name, purpose, status, is_archived, started_at, finished_at, and created_at.

​

List document insights

Returns your document insights: the fields Coverbase extracts from documents. Each item has id, field_name, field_key, field_description, field_type, field_mode, enabled, is_archived, document_types, and update_policy.

​

List a document’s insight values

Returns the insight values Coverbase extracted from one document. The response has items and total. Each item has id, config_id, field_name, value, source_quote, source_page_number, confidence, source_type, and answer_accepted_at.

​

Create an Inspect schedule

Returns 201 with the new schedule. A drift schedule repeats every interval_seconds; every other purpose runs monthly on day_of_month. An unknown application returns 422 with target_not_found, an archived one target_archived, and an invalid cadence or control set schedule_invalid. To change a schedule’s cadence or control sets, send PATCH /v1/inspect-schedules/{schedule_id} with any of day_of_month, interval_seconds, and control_set_ids. To stop it for good, send DELETE /v1/inspect-schedules/{schedule_id}.

​

Create and manage document insights

To create an insight, send POST /v1/document-insights. It returns 201 with the insight. To change an insight, send PATCH /v1/document-insights/{config_id} with the fields to change. Send reviewer_user_id: null to clear the reviewer. apply_mode decides what the new definition reaches: forward_only (the default) re-runs nothing, selected re-runs the documents in document_ids, and all_historical re-runs every in-scope document an older revision filled. A re-run starts in the background and its id comes back as backfill_id; poll GET /v1/document-insight-backfills/{backfill_id}. When a running backfill or a daily ceiling blocks the re-run, nothing is saved and the response is 409, 422, or 429 with backfill_refused. Making a synthesis insight anything but text returns 422 with synthesis_needs_text. To edit many insights at once, send POST /v1/document-insights/bulk-update with config_ids (up to 200) and any of enabled, group_id, clear_group, add_document_types, and remove_document_types. Document types are added and removed, never replaced. To archive many at once, send POST /v1/document-insights/bulk-archive with config_ids; API keys cannot do this. Both return updated_count and the changed insights in items. To retire an insight and keep its values, send POST /v1/document-insights/{config_id}/archive. To bring it back, send POST /v1/document-insights/{config_id}/restore.

​

Targets

A target links an insight to a built-in contract or document field it fills. To list them, send GET /v1/document-insights/{config_id}/targets. To add one, send POST /v1/document-insights/{config_id}/targets with object_type (contract or vendor_document), field_name, and optionally conflict_policy (fill_if_empty, latest_document_wins, never_overwrite), min_confidence (low, medium, high), require_grounded, and enabled. A pairing no parser covers returns 422 with target_not_supported; a field the insight already fills returns 409 with target_exists. To change a target, send PATCH /v1/document-insight-targets/{target_id}. To stop filling the field, send DELETE /v1/document-insight-targets/{target_id}. Values already written stay.

​

Groups

To list groups, send GET /v1/document-insight-groups. To create one, send POST /v1/document-insight-groups with name and optionally description, document_types, sort_order, and enabled. To change one, send PATCH /v1/document-insight-groups/{group_id}; changing document_types rescopes every insight that inherits from the group. To delete one, send DELETE /v1/document-insight-groups/{group_id}. Its insights stay, outside any group.

​

Coverage

GET /v1/document-insight-stats returns one row per insight with how many eligible documents it applies to, how many hold a value, and its fill rate. Pass config_id one or more times to read only those insights.

​

Manage dark web monitoring

To read the policy, send GET /v1/dark-web/config. To change it, send PATCH /v1/dark-web/config with any of is_enabled, monitor_organization, vendor_scope (radar_monitored or all), enabled_sources, lookalikes_for_vendors, confidence_threshold (0 to 1), and business_hours. Coverbase re-derives the watchlist right away, and switching monitoring on creates the dark web roles.

​

Review an exposure

To record a triage decision, send PATCH /v1/dark-web/exposures/{exposure_id}/review. Only the fields you send change. Moving to new, confirmed, or with_legal runs your alert rules. Errors: 404 exposure_not_found, 422 assignee_not_member, 422 review_not_allowed.

​

Watchlist

To list watched identifiers, send GET /v1/dark-web/watchlist. Values are masked. To add one, send POST /v1/dark-web/watchlist with subject_kind (organization or vendor), asset_type, value, and vendor_id for a vendor identifier. Optional fields: label, role (domains), program_vendor_id, card_kind, card_network (BINs), and linked_asset_id (mailboxes). Adding an identifier already there re-enables it. To turn one on or off or change its details, send PATCH /v1/dark-web/watchlist/{asset_id}. To stop watching it, send DELETE /v1/dark-web/watchlist/{asset_id}; a derived identifier is switched off instead of removed.

​

Playbooks

To list every response checklist, send GET /v1/dark-web/playbooks. To replace one with your own steps, send PUT /v1/dark-web/playbooks/{key} with steps, a list of { "id": optional, "label": required }. To go back to Coverbase’s default, send DELETE /v1/dark-web/playbooks/{key}.

​

Manage certificates and prequalification

To record a certificate by hand, send POST /v1/vendor-certificates with vendor_id, certificate_type, name, and optionally issuer, scope, result, coverages, valid_from, valid_to, and vendor_document_id. Coverbase re-checks the vendor’s prequalification. To record a person’s check, send PATCH /v1/vendor-certificates/{certificate_id}/verification with verification_status (unverified, verified, discrepancy) and verification_note. To archive a certificate, send DELETE /v1/vendor-certificates/{certificate_id}. To ask a vendor for a certificate, send POST /v1/vendor-certificate-requests with vendor_id, certificate_type, message, and due_at. The response gives the unsent supplier portal’s portal_id. To ask for renewals in bulk, send POST /v1/certificate-renewal-jobs with certificate_ids, message, and due_at. It returns 202 with the job. To follow it, poll GET /v1/certificate-renewal-jobs/{job_id} until status is final; the counts show how many requests were sent, skipped, or failed. To pull certificates from a connected network now, send POST /v1/certificate-networks/{network}/sync with isnetworld, avetta, or ecovadis. It returns 202.

​

Rule sets

A rule set lists the certificates vendors must hold. To list them, send GET /v1/prequalification-rule-sets. To create or replace one, send POST /v1/prequalification-rule-sets or PUT /v1/prequalification-rule-sets/{rule_set_id} with name, description, applies_to, rules, expiry_reminder_days, and blocks_on_failure. Coverbase re-checks every governed vendor in the background. To archive one, send DELETE /v1/prequalification-rule-sets/{rule_set_id}. To see where a vendor stands, send GET /v1/vendors/{vendor_id}/prequalification. To re-check it now, send POST /v1/vendors/{vendor_id}/prequalification/refresh.

​

Get a vendor’s security benchmark

Returns where the vendor’s outside-in security score sits among your other rated vendors: score, rated_vendors, percentile (null until enough vendors are rated), and grade_counts.

​

Query the Certificate Vault

Returns certificates that match a unified filter, in the same shape as the list endpoint. To see which certificate networks you connected, send GET /v1/certificate-networks. Each item has network, display_name, is_connected, certificate_count, and last_synced_at. Credentials are never returned.

​

Correct a vendor’s external security scan

These endpoints change what the outside-in scan sees. The scan target belongs to the company, so every org linked to it sees the correction. Each write that changes the scan starts a rescan; rescan_started false means the rescan is queued, not dropped.

• To point the scan at the right domain, send POST /v1/vendors/{vendor_id}/external-security/rescan with domain. The response gives the host it reduced to.
• To record whether an attributed asset is the vendor’s, send POST /v1/vendors/{vendor_id}/external-security/estate-reviews with kind (domain or host), identifier, review (unreviewed, confirmed, disputed), and an optional note. Only a change into or out of disputed starts a rescan.
• To add hosts or addresses the scan missed, send POST /v1/vendors/{vendor_id}/external-security/estate-assets with identifiers and an optional note. The response lists added, already_present, and rejected.
• To see the companies the rating is compared against, send GET /v1/vendors/{vendor_id}/external-security/peers. To queue the work a stale comparison needs, send POST /v1/vendors/{vendor_id}/external-security/peers/refresh. Set force to re-choose the peers.

Errors use the codes not_found, forbidden, and invalid.

​

List continuous monitoring findings

To list findings about your vendors, send GET /v1/vendor-scan-results with optional vendor_id, risk_category, severity_low, severity_high, limit, and offset. To get one, send GET /v1/vendor-scan-results/{scan_result_id}. Each item has title, summary, risk_category, severity, urls, and published_at.

​

Review an extracted insight value

To accept an extracted value as the answer, send POST /v1/document-insight-values/{data_id}/accept with the value you saw in value_string, value_number, value_date, or value_boolean. A value that changed since returns 409 with value_changed. Accepting does not claim the quote was verified. To mark a value correct or incorrect, send POST /v1/document-insight-values/{data_id}/verdict with verdict (correct, incorrect, or null to clear).

​

Teach a document insight with examples

A worked example shows an insight an excerpt and the answer it should give. An enabled example is part of what extraction is asked, so each change starts a new revision of the insight.

• To list examples, send GET /v1/document-insights/{config_id}/examples.
• To add one, send POST /v1/document-insights/{config_id}/examples with document_excerpt, expected_value (the answer in the insight’s type, or null for “not in the document”), and optionally explanation, document_id, and enabled. An answer that does not fit the insight’s type returns 422 with invalid_expected_value.
• To change one, send PATCH /v1/document-insight-examples/{example_id}. Only the fields you send change.
• To delete one, send DELETE /v1/document-insight-examples/{example_id}.
• To build an example from an extracted value, send POST /v1/document-insight-values/{data_id}/to-example with an optional explanation. A value that cites no document text returns 422 with no_cited_text.

​

Re-run insights over existing documents

A backfill re-extracts insights in the background and costs model calls. Manual values are never overwritten. To see what a backfill would do, send POST /v1/document-insight-backfills/preview. It runs nothing. The preview returns document_count, insight_count, estimated_model_calls, manually_cleared_count, and blocked_reason when it could not start now. To start one, send the same body to POST /v1/document-insight-backfills. It returns 202 with the backfill. Poll GET /v1/document-insight-backfills/{backfill_id} until status is completed, failed, or cancelled. A run over the per-run or per-day ceilings, or with nothing to do, returns 422, 409, or 429 with backfill_refused. To stop dispatching more documents, send POST /v1/document-insight-backfills/{backfill_id}/cancel. Work already started finishes.

​

Escalate an exposure, sync the watchlist, and set retention

• To open a finding from an exposure, send POST /v1/dark-web/exposures/{exposure_id}/escalate with optional title and assigned_to_id. A second call returns the same finding_id.
• To re-derive the watchlist from your organization and vendor records now, send POST /v1/dark-web/watchlist/sync. The response counts identifiers created, kept, and archived.
• To read how long each class of dark web data is kept, send GET /v1/dark-web/retention. To change it, send PUT /v1/dark-web/retention with exposures_years, evidence_years, audit_years, and sweep_history_years. A shorter period purges older data at the next nightly run.

​

Work with your organization’s own documents

Org documents are files your organization owns, such as policies, questionnaire and report templates, and exports.

• To list them, send GET /v1/org-documents with optional document_type, search, limit, and offset.
• To download one, send GET /v1/org-documents/{document_id}/download. The response gives a presigned url that is valid for expires_in seconds. Follow it with a plain GET and no auth header.
• To rename, retype, archive, or restore one, send PATCH /v1/org-documents/{document_id} with any of name, document_type, and is_archived.
• To upload one, send POST /v1/org-documents as multipart/form-data with file and optional document_type and name. It returns 201 with the document. An assessment_report_template must be a valid .docx: another extension returns 400 with template_must_be_docx, and a file that does not open as Word returns 400 with invalid_template.

​

Correct or remove extracted values

• To replace an extracted value with the right one, send POST /v1/document-insight-values/{data_id}/correct with one of value_string, value_number, value_date, or value_boolean. The correction becomes a manual value that no re-extraction overwrites, and Coverbase writes it to linked fields. A value that does not fit the insight’s type returns 422 with invalid_value.
• To delete a value, send DELETE /v1/document-insight-values/{data_id}.
• To judge many values at once, send POST /v1/document-insight-values/bulk-verdict with ids and verdict (correct, incorrect, or null). The response gives updated_count and found_count; a value that already holds the verdict is skipped.

​

Fill a custom field from a document insight

Promoting an insight links it to a custom field on vendors, services, assessments, or contracts, so each extracted value also fills that field.

• To see which custom fields an insight could fill, send GET /v1/document-insights/{config_id}/promotion-options. compatible_field_type names the custom field type the insight can fill, or is null when its type cannot fill one yet. Each item gives custom_field_id, field_name, field_type, applied_to, and is_linked.
• To link it, send POST /v1/document-insights/{config_id}/promote with either custom_field_id (an existing field) or new_field_name and applied_to (vendor, service, assessment, or contract) to create one. Optional fields are require_grounded (default true), min_confidence (high, medium, or low; default medium), conflict_policy (never_overwrite, fill_if_empty, or latest_document_wins; default fill_if_empty), and backfill (default true, which fills the field from existing documents in the background). The response gives custom_field_id, created_custom_field, and backfill_queued. An archived insight returns 409 with document_insight_archived, a field that already has another autofill source returns 409 with custom_field_has_autofill_source, and a type or target mismatch returns 422 with promotion_invalid.
• To stop filling a field, send DELETE /v1/document-insights/{config_id}/custom-fields/{custom_field_id}. It returns 204. Values already written stay. A field the insight does not fill returns 409 with custom_field_not_linked.

​

Train a decision model

A decision model is the model document insight extraction uses for your organization. You can start one from a base model, train it on your verified values, and switch extraction to it once it scores at least as well as the standard model. Responses never include storage locations or job identifiers.

• To list models, send GET /v1/document-insight-models. The response also gives base_model_ids you can start from, active_model_id, and training_configured.
• To start one, send POST /v1/document-insight-models with name and base_model_id. An unlisted base model returns 422 with base_model_not_allowed.
• To collect verified values into its training set, send POST /v1/document-insight-models/{model_id}/dataset. dataset_stats gives the counts.
• To compare it with the standard model, send POST /v1/document-insight-models/{model_id}/evaluate with an optional max_documents (1 to 100, default 25). It returns 202 and costs model calls. Poll the list until eval_result.status is no longer running.
• To start fine-tuning, send POST /v1/document-insight-models/{model_id}/training. Training runs for hours. To record its progress, send POST /v1/document-insight-models/{model_id}/training/sync.
• To switch extraction to it, send POST /v1/document-insight-models/{model_id}/activate. A trained model is held back until its accuracy check passes; activation_blocked_reason says why.
• To retire it, send POST /v1/document-insight-models/{model_id}/retire. Retiring the active model returns extraction to the standard model. API keys cannot retire.

A step the model’s state refuses, such as evaluating a retired model or training without a dataset, returns 409 with decision_model_conflict.

​

Add an Inspect application

Adds an application for Inspect to sign in to and check, and returns it with 201. When the application’s login domain matches exactly one of your vendors, Coverbase links that vendor. To add up to 200 applications in one request, send POST /v1/inspect-applications/bulk with applications, a list of the same objects. Coverbase validates every entry before it creates any, so one invalid entry refuses the whole batch. The response has items in request order.

​

Response

​

Errors

​

Get or change an Inspect application

To read one application, send GET /v1/inspect-applications/{application_id}. It returns the same shape as the create response. An unknown ID returns 404 with application_not_found. To rename an application or change its login URL, send PATCH /v1/inspect-applications/{application_id} with display_name, login_url, or both. Omitted fields keep their value. To make an Okta or Entra application use the URL its identity provider reports, send login_url: null. A password_url or oauth_google application keeps its URL and returns 422 with login_url_required. A blank name returns 422 with display_name_blank. To link an application to one of your vendors, send PUT /v1/inspect-applications/{application_id}/vendor with vendor_id. An unknown or archived vendor returns 404 with vendor_not_found. To set the platform, send PUT /v1/inspect-applications/{application_id}/platform with platform_key (or null to clear it) and an optional api_authority. When you leave out api_authority, the current one stays. To link several applications to their suggested vendors, send POST /v1/inspect-applications/link-suggested-vendors with up to 200 application_ids. An application that already has a vendor, or whose match is ambiguous, stays as it is. When an ID is unknown, nothing changes and the endpoint returns 404 with application_not_found. All of these need the integration:update:org permission, except the read, which needs integration:read:org.

​

Archive or delete an Inspect application

To stop Inspect checking an application and keep its history, send POST /v1/inspect-applications/{application_id}/archive. To restore it, send POST /v1/inspect-applications/{application_id}/unarchive. To archive or restore up to 200 at once, send POST /v1/inspect-applications/bulk-archive with application_ids and is_archived. To delete an application for good, send DELETE /v1/inspect-applications/{application_id}. Coverbase removes its saved sign-in sessions and stored credentials, then returns 204. You cannot undo a delete. API keys cannot archive, restore, or delete applications. A signed-in user must do it.

​

Errors

​

Read setup options and platforms

To list what you can pick when you start an inspection, send GET /v1/inspect-setup-options. The response has applications (each with id and display_name) and control_sets (each with id, name, and control_count). Only internal control sets with at least one active control appear. To list the platform keys you can assign to an application, send GET /v1/inspect-platforms. The response has platform_keys. Both need the integration:read:org permission.

​

Read and change an application’s config

Returns how Inspect signs in to an application and calls its API. Each credential field says whether a value is stored. The API never returns a stored credential or where it is kept.

​

Response

To set an application’s API settings, send any of api_authentication_parameters and request_parameters (objects keyed by the key the read returns) and api_authority. Coverbase validates every value before it saves any, and returns the updated config. You set sign-in and API credentials in Coverbase, not through the API, so a credentials field returns 422. The read needs integration:read:org and the update needs integration:update:org.

​

Errors

​

Prepare Inspect plans

A plan says which evidence Inspect collects for one control on one platform, and how. Inspect can start an inspection only when every control in the chosen set has a ready plan. Reports whether a control set is ready for an application. Needs integration:read:org. The response gives the set’s readiness and each control’s plan or preparation. To prepare the missing plans, send control_set_id, application_id, and an optional browser_evidence_allowed. Preparation runs in the background, and the response is the readiness after Coverbase queued it. Poll GET /v1/inspect-plans/readiness until the set is ready. Needs integration:run:org.

​

Errors

​

Read and edit an Inspect plan

To read a plan, send GET /v1/inspect-plans/{plan_id}. The response has id, source_control_id, platform_key, version, scope (public or organization), is_latest_version, superseded_reason, outdated, plan_content_hash, the full plan, and created_at. outdated is true when newer documentation or a newer planner would build a different plan. To list a plan’s published versions without their bodies, send GET /v1/inspect-plans/{plan_id}/versions. Each item has id, version, plan_content_hash, is_latest_version, superseded_reason, published_by_user_id, derived_from_plan_id, and created_at. To edit a plan, send the whole edited plan with the plan_content_hash you read:

• To check an edit without saving it, send POST /v1/inspect-plans/{plan_id}/revisions/validate. The response gives the plan_content_hash that publishing would store.
• To publish it as the next version, send POST /v1/inspect-plans/{plan_id}/revisions. It returns 201 with the new version.

To customize a public plan, also send control_id, one of your own controls the plan covers. You can change wording and route hints. You cannot change what evidence the plan collects. Reads need integration:read:org. Edits need integration:update:org.

​

Errors

​

Regenerate an Inspect plan

When a plan is outdated, you choose when to replace it. To retire your organization’s plan and prepare a fresh one, send POST /v1/inspect-plans/{plan_id}/regenerate. The retired version stays readable, and inspections that used it keep it. The response has superseded_plan_id and the preparation, which is null when a current public plan already covers the control. To redesign how Inspect checks one requirement after a run failed it, send POST /v1/inspect-plans/{plan_id}/requirements/{requirement_key}/regenerate with the run_id. The plan stays live until the new version publishes. The response has the preparation. Both need integration:update:org.

​

Errors

​

Start an inspection

Starts an inspection of one application against one or more control sets, and returns it with 201. The inspection runs in the background. To follow it, poll GET /v1/inspections/{inspection_id}. Every control needs a ready plan first, so check GET /v1/inspect-plans/readiness and prepare missing plans with POST /v1/inspect-plans/ensure. Needs integration:run:org.

​

Response

​

Errors

​

Find inspections

To read one inspection, send GET /v1/inspections/{inspection_id}. It returns the same shape as the create response. An unknown ID returns 404 with inspection_not_found. To filter inspections, send POST /v1/inspections/query with an optional filter in the unified filter language, sort, exclude_probes, limit (1 to 500, default 50), and offset. The response has items in the shape above, total, limit, and offset. Both need integration:read:org.

​

Archive, cancel, or retry inspections

• To archive or restore up to 500 inspections, send POST /v1/inspections/bulk-archive with inspection_ids and is_archived (default true). API keys cannot archive or restore inspections, and the call needs integration:update:org and integration:archive:org.
• To cancel every unfinished control of up to 500 inspections, send POST /v1/inspections/bulk-cancel with inspection_ids. affected_ids lists the inspections that had a control to cancel.
• To cancel some controls of one inspection, send POST /v1/inspections/{inspection_id}/runs/bulk-cancel with run_ids.
• To run finished controls again, send POST /v1/inspections/{inspection_id}/runs/bulk-retry with run_ids. Set use_current_control to true to run each control’s current version. When that version has no ready plan, nothing restarts, Coverbase starts preparing the plan, and the call returns 409 with plans_not_ready.

Cancel and retry need integration:run:org. Each returns affected_ids.

​

Errors

​

Read the Inspect overview

To read your posture score across each application’s latest scored inspection, send GET /v1/inspect-posture. The response has percent, which is null until an application has a scored inspection, and app_count. To read the overview, send GET /v1/inspect-summary with an optional days (1 to 365, default 30). The response counts issues (issues_open, issues_resolved, issues_dismissed, issues_total, and issues_by_severity), findings (findings_new, findings_overdue, findings_total), applications (applications_connected, applications_inspected, applications_never_inspected, applications_with_connection_issues), and runs (runs_completed, runs_partial, runs_failed, runs_total). top_vendors and top_applications rank by issue count, each with id, name, and issue_count. Both need integration:read:org.

​

Work with the identity directory

The identity directory lists the people and services Inspect found in Okta, Entra, and inspected applications, with the accounts each holds.

• To count identities by the views the dashboard offers, send GET /v1/inspect-identities/summary. The response has identities, with_accounts, guests, admin_observed, observed, needs_attribution, observations_total, and observations_attributed.
• To filter identities, send POST /v1/inspect-identities/query with an optional filter, sort, search, limit (1 to 500, default 50), and offset. Each item has id, display_name, primary_email, association, account_count, admin_account_count, needs_review_count, and latest_observed_at.
• To assign accounts Inspect observed to an identity, send PUT /v1/inspect-accounts/owner with account_ids and identity_id. To hand the accounts back to automatic matching, send identity_id: null. Only accounts known from inspections can be assigned.
• To move every observed account of some identities to another identity, send POST /v1/inspect-identities/merge with identity_ids and into_identity_id. You cannot merge away an identity from Okta or Entra.
• To set which SaaS platform an Okta or Entra application is, send PUT /v1/inspect-idp-applications/{application_id}/platform with platform_key, or null to clear it.
• To read one identity, send GET /v1/inspect-identities/{identity_id}. It takes limit (1 to 100, default 25) and offset for its accounts. The response has the identity’s emails, directory records (principals), a page of accounts with the properties read from each, its detections, and account_count.
• To read what an identity did in Okta or Entra, send GET /v1/inspect-identities/{identity_id}/events with limit and offset. The response has sources, the newest events first, and total_count.
• To see why an account belongs to an identity, send GET /v1/inspect-identities/{identity_id}/accounts/{account_id}/evidence with limit (1 to 100, default 5), offset, and kind (all, events, or observations). The response has items, each an observation with the application, run and time it came from.
• To list the applications that hold accounts, send GET /v1/inspect-account-applications with an optional search, ids, and limit (up to 100).
• To list application credentials, such as API keys and service tokens Inspect found, send GET /v1/inspect-credentials. Filter with application_id (repeatable) and classification (ownerless_credential, unused_credential, or expired_credential). The response is metadata only: type, owner, expiry, last use, and detections. It never holds a secret value.
• To rebuild the whole inventory, send POST /v1/inspect-identities/reconcile. It returns 202 with request_id and queued. Only an organization admin can start a rebuild, so API keys cannot. Poll GET /v1/inspect-identities/reconcile/{request_id}, which returns status: queued, running, succeeded, or failed.

An owner change or merge returns request_id and queued. Coverbase then rebuilds the identity inventory in the background, so counts follow the decision within a few minutes. Reads need integration:read:org and changes need integration:update:org. A full rebuild needs integration:run:org.

​

Errors

​

Manage saved sign-in sessions

Inspect saves a sign-in session (an auth context) per single sign-on provider or application, and reuses it across runs. The API returns each session’s id, label, principal_login, status, allowed_domains, last_validated_at, last_stale_at, last_stale_reason, and last_error. It never returns browser identifiers.

• To list them, send GET /v1/inspect-auth-contexts.
• To create the session for a provider, send POST /v1/inspect-auth-contexts with optional label, provider_config, and allowed_domains. Leave out provider_config for Okta. When a session for the provider exists, Coverbase returns it. The session starts empty, and Inspect signs in on the next run.
• To make Inspect sign in again, for example after a password change, send POST /v1/inspect-auth-contexts/{auth_context_id}/stale with an optional reason.
• To sign a single sign-on session in now, send POST /v1/inspect-auth-contexts/{auth_context_id}/bootstrap. It returns 202 with the session, and the sign-in runs in the background. A sign-in already under way comes back as it is. An application’s session signs in only when an inspection reaches its sign-in page, so the call returns 422.

Listing needs integration:read:org. Creating and flagging need integration:update:org. Signing in now needs integration:run:org.

​

Errors

​

Find documentation for a control

Inspect builds plans from vendor documentation for each platform.

• To list the documents for an application’s platform, send GET /v1/inspect-applications/{application_id}/documentation. The response has platform_key, bundle_id, activated_at, and documents, each with key, title, usage, and canonical_url. An application without a platform has no documents.
• To search for the documentation a control needs, send POST /v1/inspect-documentation-discovery-runs with control_id and application_id. It returns 202 with the run. A run already queued for the same pair is returned instead of a new one.
• To follow a run, send GET /v1/inspect-documentation-discovery-runs/{run_id}. The run has id, control_id, application_id, platform_key, status, phase, outcome, failure_code, resource_bundle_id, created_at, started_at, and finished_at.
• To read one document’s text, send GET /v1/inspect-applications/{application_id}/documentation/{document_key} with a key from the list. The response has key, title, media_type, text, and truncated, which is true when the text stopped at one million characters.

Reads need integration:read:org. Starting a run needs integration:run:org.

​

Errors

​

Read Okta and Entra connections

• To list the applications synced from Okta, send GET /v1/okta-integration/applications. For Microsoft Entra, send GET /v1/entra-integration/applications. Both take limit (1 to 500, default 100) and offset. Each item has id, provider_app_id, display_name, status, sign_on_mode, login_url, platform_key, vendor_id, and last_synced_at.
• To read how often Coverbase syncs Okta, send GET /v1/okta-integration/schedule. The response has connected, sync_interval_hours, last_synced_at, and next_sync_at.
• To change it, send PUT /v1/okta-integration/schedule with sync_interval_hours set to 6, 12, 24, or 168, or null to sync only when someone asks.
• To read the latest sync, send GET /v1/okta-integration/sync. The response has job, which is null when Okta never synced. A job has id, kind, status, stage, incremental, inventory_ready, applications_ready, applications_total, access_synced_count, groups_synced_count, can_resume, record counts, last_error, started_at, and completed_at. A sync that stopped reporting progress reads as failed.
• To disconnect Okta, send DELETE /v1/okta-integration. Inspect stops syncing it and keeps the synced history. It returns 204.
• To sync Okta now, send POST /v1/okta-integration/sync with optional resume (continue the last failed sync) and full (reread everything). It returns 202 with sync_job_id and status. A sync already running comes back instead of a new one. Poll GET /v1/okta-integration/sync.
• To check the connection against Okta, send POST /v1/okta-integration/verify. The response has status (connected or error), error_category, remediation_hint, and requirements, each with id, label, status, and detail.
• To compare the scopes Inspect needs with the ones your Okta app granted, send GET /v1/okta-integration/scopes. The response has requested_scopes, granted_scopes, and missing_scopes.
• To read one Okta application, send GET /v1/okta-integration/applications/{application_id}. The response has its sign-on mode, whether Inspect can sign in to it, its assignment count, and its vendor link. It leaves out the raw Okta record, which can hold credentials. To list who is assigned to it, send GET /v1/okta-integration/applications/{application_id}/users.
• To list the people in your Okta directory with their application accounts and findings, send GET /v1/okta-integration/identities with limit (1 to 500, default 100) and offset. For counts only, send GET /v1/okta-integration/identities/summary.
• To read the Okta user Inspect signs in as, send GET /v1/okta-integration/inspection-identity. The response has login, status, credentials_configured, grants, recent_actions, manual_steps, and write_allowed. It says whether a password is stored and never returns it.
• To provision that user and assign it to applications, send POST /v1/okta-integration/provision with application_ids, an optional login, and approved: true. To remove its access, send POST /v1/okta-integration/deprovision with approved: true, and delete_user: true to delete the Okta user too. Both return 202 and run in the background.
• To check every Okta application Inspect can sign in to, send POST /v1/okta-integration/inspect-runs. It returns 202 with the run. Poll GET /v1/okta-integration/inspect-runs/{run_id}, which adds each application’s result.
• For Microsoft Entra, send POST /v1/entra-integration/verify to check the Microsoft Graph permissions, and POST /v1/entra-integration/sync to sync applications, people, and assignments. The sync finishes before the call returns. To read the Entra user Inspect signs in as, send GET /v1/entra-integration/inspection-identity. To provision it, send POST /v1/entra-integration/provision with application_ids, an optional user_principal_name, and approved: true.

Provisioning and deprovisioning change access in your identity provider. Only an organization admin can do them, and API keys cannot. Syncing, verifying, and starting an inspect run also stay with an organization admin. Changing the schedule and disconnecting stay with an organization admin, so API keys cannot do them. You connect Okta and Entra, store their credentials, and rotate Okta keys in Coverbase.

​

Errors

​

Watch or download a control run’s browser

When Inspect checks a control in a browser, it records each browser tab.

• To list a run’s recorded tabs, send GET /v1/inspections/{inspection_id}/runs/{run_id}/replay. The response has status (ready, preparing, or unavailable) and pages, each with page_id. A recording reads as preparing for about a minute after the run finishes.
• To download one tab, send GET /v1/inspections/{inspection_id}/runs/{run_id}/replay/pages/{page_id}. The response is an HLS playlist (application/vnd.apple.mpegurl) whose segment links are short-lived, so play or save it right away.
• To watch a running control, send GET /v1/inspections/{inspection_id}/runs/{run_id}/live-view. The response has live_view_url and pages, each with page_id, title, and live_view_url. The fields are null when the control is not running. Anyone with a live view link can watch until it expires, so do not store or share it.

These responses are never cached. All three need integration:read:org.

​

Errors

​

Run probes

A probe is a custom check Inspect runs on one application, once as a preview or on a schedule. Each run is a sample.

1. To draft a probe, send POST /v1/inspect-probes/prepare with target_id (the application), objective, and an optional name. Inspect plans checkpoints from the platform’s documentation. Nothing is saved.
2. To save the draft, send POST /v1/inspect-probes with the draft’s draft_id, target_id, name, resource_bundle_id, and spec, and an optional interval_seconds (900 to 604800, default 3600). It returns 201 with the probe, paused.
3. To run a sample now, send POST /v1/inspect-probes/{probe_id}/preview with an idempotency_key. It returns 202 with the sample’s inspection_id and run_id. Sending the same key again returns the first sample.
4. To turn on its schedule, send PATCH /v1/inspect-probes/{probe_id}/automation with enabled: true and an optional interval_seconds. Inspect needs a reviewed preview of the current procedure and every requirement ready, or the call returns 409.

To change the procedure, send POST /v1/inspect-probes/{probe_id}/versions with expected_version (the version you read), resource_bundle_id, and spec. When someone published since, it returns 409.

• To list probes, send GET /v1/inspect-probes with an optional application_id, limit (1 to 100, default 25), and offset. To filter them, send POST /v1/inspect-probes/query with filter, sort, search, application_id, limit, and offset. The response has probes and total.
• To read one probe with its procedure, readiness, automation, and latest sample, send GET /v1/inspect-probes/{probe_id}.
• To list samples, send GET /v1/inspect-probes/{probe_id}/runs. To read one sample with each checkpoint’s result and its evidence, send GET /v1/inspect-probes/{probe_id}/runs/{run_id}.
• To keep a sample for an auditor, send GET /v1/inspect-probes/{probe_id}/runs/{run_id}/package. It returns a zip with a manifest, a printable summary, and the screenshots. X-Missing-Screenshots counts screenshots Coverbase could not read. The response is never cached.
• To see each scheduled launch and whether a sample started, send GET /v1/inspect-probes/{probe_id}/deliveries with optional before, after, exclude_accepted, and limit.

The definitions routes are deprecated. New probes do not need a definition.

​

Errors

​

Raise an evaluation as a Finding

When an Inspect evaluation fails, you can raise it as a Finding.

• Send POST /v1/inspect-evaluations/{evaluation_id}/finding. A new Finding returns 201 with finding and created: true, and Coverbase drafts its recommended remediation in the background. When the evaluation already raised one, the call returns 200 with that Finding and created: false. It needs finding:create:org.
• To draft the recommended remediation for a Finding Inspect raised whose guidance is empty, send POST /v1/findings/{finding_id}/recommended-remediation/draft. It returns 202. Guidance someone wrote or cleared is never replaced, so the call returns 409. It needs finding:update:org.
• To read the guidance, send GET /v1/findings/{finding_id}/recommended-remediation. The response has status (available, drafting, cleared, or absent) and recommended_remediation. It needs finding:read:org.

​

Errors

​

Poll an operation’s events

Inspect logs each step of a run, a sign-in, a plan preparation, or a documentation search. To read the log, send GET /v1/inspect-events with exactly one of run_id, auth_context_id, application_id, plan_preparation_id, or documentation_discovery_run_id. Events come oldest first, up to limit (1 to 500, default 500). To read only newer events, pass the last sequence you read as after_sequence. This replaces the dashboard’s live stream. It needs integration:read:org.

​

Decide an access removal request

A workflow can propose removing identity provider assignments from a vendor’s users. Approving one stays in Coverbase.

• To reject a request, send POST /v1/access-removal-requests/{request_id}/reject with an optional reason.
• To close a request after a person removed the rows in the identity provider, send POST /v1/access-removal-requests/{request_id}/complete-manually with the item_ids they removed.

Both return the request. Deciding who keeps access stays with a person, so API keys cannot do either. When the request names approvers, you must be one. Both need integration:update:org.

​

Export, import, and test insight definitions

• To export your insight library, send GET /v1/document-insight-definitions with an optional include_archived. Each item is a portable definition keyed by field_key, with no ids and no extracted values.
• To import definitions, send POST /v1/document-insight-definitions with definitions (up to 500) and an optional overwrite_existing (default false). An insight whose field_key already exists is skipped unless you overwrite. The response lists created_field_keys, updated_field_keys, and skipped_field_keys.
• To try a definition before saving it, send POST /v1/document-insight-definitions/test with field_name and any of field_description, field_type, field_mode, document_types, sample_size (1 to 5), config_id, and document_ids. It runs one model call per document and saves nothing. Each item gives the answer, its quote, and, with config_id, whether it matches the value the insight holds now. A scope with no readable documents returns 422 with no_documents_to_test.

​

Delete a document insight

Deleting removes the insight and every value it ever extracted. It cannot be undone, so it takes two steps.

1. Archive the insight with POST /v1/document-insights/{config_id}/archive.
2. Send GET /v1/document-insights/{config_id}/delete-preview. The response gives extracted_value_count and linked_custom_field_names.
3. Send DELETE /v1/document-insights/{config_id}?acknowledged_value_count=N, where N is the count the preview gave. It returns 204.

API keys cannot delete an insight. An insight that is not archived returns 409 with insight_not_archived, a count that changed returns 409 with value_count_changed, and an insight that still fills a custom field returns 409 with linked_custom_fields. Unlink those fields first.

​

Read value history and coverage

• To read every value change for one insight, newest first, send GET /v1/document-insights/{config_id}/events with limit (1 to 200) and offset. For one value’s timeline, send GET /v1/document-insight-values/{data_id}/events. Each item gives event_type, trigger, actor_name, document_name, before, and after.
• To read every recorded revision of a definition, send GET /v1/document-insights/{config_id}/revisions.
• To read the coverage matrix, send GET /v1/document-insight-coverage with optional document_type and config_id, each repeatable. rows gives each document type’s totals, and cells gives each insight’s eligible, filled, grounded, needs_review, never_attempted, and fill_rate per type.
• To see what waits for a person, send GET /v1/document-insight-inbox. It counts field_changes, disagreements, unverified_evidence, and accuracy_misses.
• To list the built-in contract and document fields an insight can fill, send GET /v1/document-insight-target-fields.

​

Browse and compare extracted values

• To filter every value in your organization, send POST /v1/document-insight-values/query with any of config_ids, document_types, vendor_ids, source_type, confidence, grounded, needs_review, has_value, search, verdict, outdated, config_revision, limit (1 to 200), and offset.
• To compare values side by side, send POST /v1/document-insight-values/pivot with document_types (1 to 20) and optional config_ids, vendor_ids, search, limit, and offset. Each row is a document, and cells maps each insight ID to its value. A missing key means nothing was extracted.

​

Evidence images

• To list a value’s verified citations, send GET /v1/document-insight-values/{data_id}/snippets. Each item gives evidence_fingerprint, the quote and page, and status. A rendered citation carries a presigned url to its page image, valid for expires_in seconds. Follow it with a plain GET and no auth header.
• To render a citation’s image, send POST /v1/document-insight-values/{data_id}/snippets with evidence_fingerprint. It returns queued and renders in the background. List the snippets again for the link. A fingerprint that matches no current citation returns 404 with citation_not_found.

​

Export an insight’s values

• To list the columns an export can hold, send GET /v1/document-insight-export-columns.
• To export, send POST /v1/document-insights/{config_id}/export with any of columns, data_ids, the value filters, include_empty, and multi_value_mode. The response gives a presigned url to the workbook, filename, expires_in, exported_rows, and available_rows. Every export is recorded on the insight’s activity.

These responses are never cached.

​

Check a decision model’s accuracy

• To read a check’s scorecard, send GET /v1/document-insight-models/{model_id}/scorecard. It gives base, candidate, and shadow scores, overall and per insight, with reviews applied.
• To work through the misses, send GET /v1/document-insight-models/{model_id}/examples with optional role, config_id, outcome, reviewed, limit, and offset.
• To settle one miss, send POST /v1/document-insight-eval-examples/{example_id}/review with decision (team_right, ai_right, both_fine, or null to clear). ai_right also corrects the checked value to the AI’s answer, which needs vendor:update on that vendor.
• To see one insight’s training set, send GET /v1/document-insight-models/{model_id}/dataset-preview?config_id=... with an optional status (train, holdout, used_as_example, or no_evidence).
• To answer live documents with a trained model beside production, send PUT /v1/document-insight-models/{model_id}/shadow with enabled. Only one model shadows at a time, and nothing it answers is saved. A model that is not trained and ready returns 409 with shadow_unavailable.

​

Run an insight on a document

• To run a saved insight on one document, send POST /v1/documents/{document_id}/insight-extractions with config_id. It costs one model call, returns the answer with its quote and confidence, and saves nothing.
• To try an unsaved definition, send POST /v1/documents/{document_id}/insight-previews with field_name and optional field_description, field_type, and field_mode. It returns 202 with a job. Poll GET /v1/document-insight-previews/{job_id} until status is completed or failed. Only the key or person that started a preview reads it.

​

Retrain the document type model

Your organization’s document type model is a fork of a shared base model. To read where both stand, send GET /v1/document-type-decision-model. To retrain your fork, send POST /v1/document-type-decision-model/train-fork. It returns 202. A run already in progress returns 409 with training_running, and a missing base model returns 409 with base_model_missing. Without the feature, both return 404 with document_type_model_not_enabled.

​

Reject a pending change

To reject a proposed field change, send POST /v1/document-insight-pending-changes/{change_id}/reject. Nothing is written to the target record. An already resolved change returns 409 with change_already_resolved. API keys cannot approve or reject changes, so a signed-in person does it.

​

Work an exposure

• To read one exposure, send GET /v1/dark-web/exposures/{exposure_id}. It adds the playbook, baseline_item_id, and follow_up_finding_id to the list fields. The matched value stays masked, and opening an exposure is audited. For its status history, send GET /v1/dark-web/exposures/{exposure_id}/history.
• To read its playbook, send GET /v1/dark-web/exposures/{exposure_id}/playbook. To tick or untick a step, send PATCH to the same path with step_id and done. A step that is not on the playbook returns 422 with step_not_on_playbook.
• To move many held exposures at once, send POST /v1/dark-web/exposures/bulk-review with exposure_ids (up to 200), action (promote or dismiss), and, to dismiss, false_positive_reason. Only exposures still in Needs review move. The rest come back in skipped with not_found or not_in_needs_review.
• To read evidence, send GET /v1/dark-web/exposures/{exposure_id}/evidence. Each capture gives its metadata and a presigned download_url for the redacted capture, valid for expires_in seconds. The content is never inline, every read is audited, and the response is never cached.
• To start a follow-up with a partner, send POST /v1/dark-web/exposures/{exposure_id}/partner-follow-up with optional title, assigned_to_id, and note. It opens a finding on the exposure’s vendor, or on the partner a program BIN runs for. It does not contact the partner: whether and how the partner hears stays your decision. A second call returns the open finding with created set to false.
• To read one vendor’s dark web picture, send GET /v1/dark-web/vendors/{vendor_id}.

Recording consent and sending an exposure to Legal never go through the API.

​

Run the dark web program

• To run a sweep now, send POST /v1/dark-web/sweeps. It returns 202. One sweep runs at a time, so a second call returns active_run_id. To list sweeps, send GET /v1/dark-web/sweeps.
• To read the setup checklist, send GET /v1/dark-web/setup. To record that a person reviewed the alert rules or the business hours, send POST /v1/dark-web/setup/confirm/{confirmation} with alert_rules_reviewed or business_hours. API keys cannot confirm a step.
• To preview a retention change, send GET /v1/dark-web/retention/preview with any of exposures_years, evidence_years, audit_years, and sweep_history_years. It counts what the next purge removes and gives next_purge_at.
• To read the program report, send GET /v1/dark-web/report with from_ts, to_ts, and optional time_zone. It returns aggregates only. Each read is audited.
• To export the queue, send POST /v1/dark-web/exposures/export with the queue filters. The response gives a presigned url to a CSV with no summary, matched value, or evidence. More than the export limit returns 413 with export_too_large.
• To read the sources, send GET /v1/dark-web/sources. To read the managed AI fraud terms, send GET /v1/dark-web/ai-fraud-terms.

​

Baseline

The baseline is the list of exposures your organization already knew about.

• To read a file’s columns, send POST /v1/dark-web/baseline/preview as multipart/form-data with file (.csv or .xlsx). It suggests a mapping and stores nothing.
• To import, send POST /v1/dark-web/baseline/import as multipart/form-data with file, mapping (a JSON object from each baseline field to a column), and dry_run. dry_run defaults to true, so send false to keep the import. A re-import replaces every item.
• To read the baseline, send GET /v1/dark-web/baseline. Identifiers are masked.

​

Alert rules

• To list the rules in evaluation order, send GET /v1/dark-web/alert-rules.
• To add one, send POST /v1/dark-web/alert-rules with the whole rule: name, is_enabled, applies_in_addition, match, recipients, channels, clock, and escalation. To replace one, send PATCH /v1/dark-web/alert-rules/{rule_id} with the whole rule. To set the order, send PUT /v1/dark-web/alert-rules/order with rule_ids. These need an organization admin.
• To see how often a rule would have fired, send POST /v1/dark-web/alert-rules/preview with match. It counts exposures first seen in the last 30 days.
• To check your SIEM’s parser, send POST /v1/dark-web/alert-rules/test. It sends a fictional, signed DarkWebExposure.Created to every webhook subscribed to dark web events, so it contacts your webhook endpoints.

​

Access

To read the roles that open dark web monitoring and what each can do, send GET /v1/dark-web/access. To create the designated roles your organization is missing, send POST /v1/dark-web/access/roles. It never changes a role that exists. API keys never change roles.