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.
An intake session (cbintksn_...) is a vendor intake request. Creating one through this API registers the vendor, creates the intake session, and kicks off AI processing that auto-answers the selected inherent risk questionnaire(s). With auto_submit, the session is then submitted to the dashboard’s Intake queue, where reviewers approve or deny it; on approval, the questionnaire-derived inherent risk scores are applied to the vendor and its services. Use this API to embed Coverbase intake inside another system (procurement tool, ticketing, internal portal): POST the request (including any free-form context and files you already have) and poll for the generated answers. All endpoints are org-scoped to the API key. See API conventions for authentication, IDs, timestamps, and the error envelope.
Not embedding intake in another system? The same request can be filed conversationally through the MCP server, with the assistant researching the vendor, confirming its identity, running your configured screening, and walking the questionnaire with the requester. See Vendor intake in chat. Both paths produce the same session and the same review queue.

​
List questionnaires

​
GET
GET /v1/intake/api/questionnaires
Lists your organization’s questionnaires so you can discover the IDs to pass as questionnaire_ids when creating an intake session. Archived questionnaires are excluded.

​
Query parameters

​
string
Optional. Filter to a single questionnaire type, for example, irq (inherent risk questionnaire), vendor_onboarding, assessment, informational.

​
Example request

cURL

​
Example response

200 OK:
​
object[]
The org’s questionnaires. Each has id (cbqsr_...), name, description (or null), type, and created_at (Unix seconds).
​
integer
Number of questionnaires returned.

​
Upload a document

​
POST
POST /v1/intake/api/documents
Uploads a file you want an intake to read, such as a SOC 2 report, a security questionnaire, or architecture notes from the procurement ticket. Returns 201 Created with a document_id (cbodoc_...). Pass that ID in document_ids when you create the intake session. This is the API equivalent of uploading files on the first step of the intake portal. Attaching files is a two-step flow:
  1. Upload each file with this endpoint and keep the returned document_id.
  2. Create the intake session with those IDs in document_ids.
The files are attached before Coverbase starts answering the questionnaire, so every answer can draw on them. An upload you never name on an intake is not used. The body is multipart/form-data, one file per request. Uploads follow the same limits as the Documents API: 100 MiB per file and the same allowed file types.

​
Which files inform the answers

Coverbase reads pdf, doc, docx, txt, md, csv, xls and xlsx files when it answers the questionnaire. Other allowed types (png, jpg, jpeg, gif, webp, ppt, pptx, rtf, xlsm, zip, msg, eml) are accepted and kept as evidence, but they do not inform the answers. A file too long for the model is also kept but skipped when answering. This matches how the intake portal treats the same files.

​
Form fields

​
file
required
The document file (multipart/form-data part). The file name’s extension decides the file type.
​
string
Display name. Defaults to the file name.

​
Headers

​
string
Optional. Replaying the same key within 24 hours returns the original 201 body and stores no second file. A retry sent while the first request is still uploading waits for it and returns the same response. See Idempotency.

​
Example request

​
Example response

201 Created:
​
string
The uploaded document (cbodoc_...). Pass it in document_ids.
​
string
Display name.
​
string
Normalized file extension (no leading dot).
​
integer
File size in bytes.
​
integer
Upload time (Unix seconds).

​
Errors

​
Create an intake session

​
POST
POST /v1/intake/api/sessions
Creates the vendor, the intake session, and one questionnaire response per questionnaire, then dispatches asynchronous AI processing. Returns 201 Created with the new session_id. Unknown questionnaire IDs return 404, and so does an organization whose vendor intake is turned off. Replaying the same external_id returns the existing session_id with 200 OK and does not reprocess; the original request’s data (including context and document_ids) is retained, and any changed fields in the replay are ignored. To analyze a vendor with updated context, create a new request with a new external_id.

​
Body fields

​
string
required
Name of the vendor the intake request is for.
​
string[]
required
Inherent risk questionnaire IDs (cbqsr_...) to auto-answer. At least one is required; unknown IDs return 404. Use GET /v1/intake/api/questionnaires to discover the IDs available in your organization.
​
string
Unstructured free-form context about the engagement: procurement ticket text, requester emails, architecture notes, security questionnaire excerpts, anything. Coverbase uses it as the highest-priority evidence when auto-answering the questionnaire (ahead of uploaded documents and web research), so the inherent risk analysis is driven by what you already know about the engagement. Maximum 100,000 characters. The context is persisted on the intake session, so later reprocessing runs reuse it.Roughly the first 20,000 characters are included in each question’s evidence (longer context is truncated per question), so put the most decision-relevant facts first rather than padding toward the limit. When your context exceeds that cap, the create response sets context_truncated: true.
​
string[]
Documents (cbodoc_...) uploaded with POST /v1/intake/api/documents to attach to this intake. At most 20. Coverbase reads them as evidence when it answers the questionnaire, and they move onto the vendor record when the intake is submitted. Each document can be attached to one intake only. If any ID cannot be attached, the request returns 422 with code documents_unavailable, a documents list naming each ID with its problem, and creates nothing:
​
string
Public website of the vendor. Improves web research and disambiguation.
​
string
Short description of what the vendor does.
​
string
What your organization intends to use the vendor for.
​
string
Your identifier for this request (for example, the procurement ticket number). Enforced unique per org; replays are idempotent and you can fetch the session by this ID later.
​
boolean
default:"false"
Submit the session for review once auto-answering completes. The request moves to Pending review in the Intake queue with its answers marked ready for review, and a person still approves or denies it. Leave it false to collect the answers over this API: the session stays a Draft and is not submitted for review. Every questionnaire must be one an intake reviewer can approve or deny; an assessment questionnaire returns 422.

​
Example request

​
Response

context_truncated is true when the submitted context exceeds the per-question evidence cap; the full text is stored, but each question prompt only receives the leading portion.

​
Get an intake session

​
GET
GET /v1/intake/api/sessions/{session_id}
Returns the session status and the per-question answers generated so far. Also available by your own identifier: GET /v1/intake/api/sessions/external/{external_id}.

​
Session status

Each entry in answers[] carries question_id, question_text, response_type (free_text, single_select, multi_select), the generated answer_text or selected_options, the model’s reasoning, and a per-answer status (answered, pending, failed). failed_count summarizes failed answers. documents[] lists the files attached with document_ids, in the order you named them. Each entry carries document_id, name, extension and size. Once the intake is submitted, each entry also carries vendor_document_id: the vendor document (cbvdoc_...) the file became. Use it with GET /v1/documents/{document_id} for the inferred document type, analysis status and a download link. Before submit vendor_document_id is null. vendor_id is the vendor (cbvndr_...) the request created or linked, or null if no vendor is linked. Use it with the Vendors API or to match an assessment back to this request (see Find the assessment an intake leads to).

​
Inherent risk score

Once status is complete, the response carries the questionnaire’s inherent risk score and tier, so your system can route the request without waiting for review.
​
number | null
The inherent risk score of the session’s IRQ answers, from 0 to 100. It is calculated the same way approval scores the vendor, including your organization’s risk domain weights, aggregation method and option score floors. When the session has several IRQs, this is the highest score, because approval only ever raises the vendor’s score. It is null until status is complete, and null when no questionnaire on the session is a scored IRQ.
​
string | null
The level on your organization’s default risk scale that raw_irq_score falls in, named the way your scale names it (for example Medium). It is null whenever raw_irq_score is null, and null if your organization has no default risk scale.
Both fields follow the current answers. If a reviewer edits an answer before approving, the score changes with it. If the reviewer overrides the score when approving, the vendor record holds the override and these fields still report the score calculated from the answers.

​
Example response

​
Find the assessment an intake leads to

An intake session does not create an assessment, and its response does not carry an assessment ID. Your organization’s workflows decide whether an assessment follows an intake, so one request can lead to no assessment or to several. To pick up the assessment:
  1. Subscribe a webhook to Assessment.Created and Assessment.Updated. Each delivery carries the assessment_id.
  2. Call GET /v1/assessments/{assessment_id}. The response carries vendor_id, status and score_percent.
  3. Match that vendor_id to the vendor_id on the intake session you created.
If your receiver misses deliveries, read them back from GET /v1/webhooks/{webhook_id}/deliveries. It lists every attempt from the last 90 days with the payload that was sent.

​
How context drives inherent risk

  1. Evidence assembly. For every questionnaire question, Coverbase builds an evidence stack ordered by reliability: your provided context, then intake follow-up responses, then the documents you attached with document_ids, then targeted web research.
  2. Auto-answering. The answer agent answers each question from that evidence, recording its reasoning per answer. Questions it cannot answer are flagged for human review rather than guessed.
  3. Scoring & review. The answered inherent risk questionnaire produces the IRQ score and per-domain risk breakdown shown on the intake request in the dashboard. The session response returns the same score and its risk level as raw_irq_score and inherent_risk_level. A reviewer approves or denies the request; approval applies the inherent risk scores to the vendor and its services.
Until it is submitted, an intake session created by this API is a Draft that no reviewer is asked to act on. With auto_submit, it is submitted as soon as its answers are generated and then follows the same triage and approval flow in the dashboard’s Intake queue as a portal-submitted request.