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.
A document (cbvdoc_...) is an evidence file (SOC 2 report, pentest report, policy, contract, questionnaire, diagram, …) that belongs to a vendor (cbvndr_...). A document can additionally be linked to any number of that vendor’s services (cbsvc_...) and assessments (cbqsrw_...). Use this API to upload a document, attach it where it belongs, list and inspect documents, fetch a short-lived download URL, re-link, and archive. All endpoints are org-scoped to the API key. See API conventions for authentication, IDs, timestamps, idempotency, pagination, and the error envelope.
MethodPathIdempotent
POST/v1/documentsYes (Idempotency-Key)
GET/v1/documents—
GET/v1/documents/{document_id}—
GET/v1/documents/{document_id}/download—
PATCH/v1/documents/{document_id}No
DELETE/v1/documents/{document_id}No
Smart limits. Uploads are capped at 100 MiB per file. Allowed file types: pdf, doc, docx, rtf, txt, md, xls, xlsx, xlsm, csv, ppt, pptx, png, jpg, jpeg, gif, webp, zip. Anything else is rejected with 400 unsupported_file_type; an oversized file is rejected with 413 file_too_large. List responses page at limit 1–200 (default 50).

​
Upload a document

​
method
POST
POST /v1/documents
Uploads a file and creates a document attached to a vendor. The request is multipart/form-data — send the file plus its links in one call. Returns 201 Created with the document object. After upload, Coverbase asynchronously classifies the document (and, where applicable, runs AI analysis). The returned status reflects this in-progress state; poll GET /v1/documents/{document_id} to observe it settle.

​
Form fields

​
file
file
required
The document file (multipart/form-data part).
​
vendor_id
string
required
The owning vendor ID (cbvndr_...).
​
service_ids
string[]
Service IDs (cbsvc_...) to link the document to. Repeat the form field once per service.
​
assessment_ids
string[]
Assessment IDs (cbqsrw_...) to attach the document to as supporting evidence.
​
document_type
string
Optional document type slug (e.g. soc2_type2_auditor_report, penetration_test_report, commercial_contract). Omit it to let Coverbase infer the type from the file. An unknown slug returns 422 invalid_document_type.
​
name
string
Optional display name. Defaults to the uploaded filename.

​
Headers

​
Authorization
string
required
Bearer ak_...
​
Idempotency-Key
string
Optional. Replaying the same key within 24 hours returns the original 201 body. See Idempotency.

​
Example request

curl -X POST "https://sandbox.api.coverbase.app/v1/documents" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Idempotency-Key: acme-soc2-2026q1" \
  -F "file=@./acme_soc2.pdf;type=application/pdf" \
  -F "vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -F "service_ids=cbsvc_1a2b" \
  -F "assessment_ids=cbqsrw_9f8e" \
  -F "document_type=soc2_type2_auditor_report" \
  -F "name=ACME SOC 2 Type II"

​
Example response

201 Created — the document object: 
{
  "id": "cbvdoc_2f1c9a7b6d5e4f3a2b1c0d9e8f7a6b5c",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "ACME SOC 2 Type II",
  "extension": "pdf",
  "size": 482113,
  "document_type": "soc2_type2_auditor_report",
  "status": "created",
  "service_ids": ["cbsvc_1a2b"],
  "assessment_ids": ["cbqsrw_9f8e"],
  "created_at": 1749340800,
  "updated_at": 1749340800
}

​
The document object

​
id
string
Document ID (cbvdoc_...).
​
vendor_id
string
Owning vendor ID.
​
name
string
Display name.
​
extension
string
Normalized file extension (no leading dot).
​
size
integer
File size in bytes.
​
document_type
string | null
The classified/declared document type slug, or null if not yet classified.
​
status
string | null
Processing status (e.g. created, analyzing, complete).
​
service_ids
string[]
Linked service IDs.
​
assessment_ids
string[]
Assessments the document is attached to.
​
created_at
integer
Creation time (Unix epoch seconds).
​
updated_at
integer
Last-update time (Unix epoch seconds).

​
List documents

​
method
GET
GET /v1/documents
Returns a paginated list of documents. Combine the filters to narrow the result.
​
vendor_id
string
Only documents owned by this vendor.
​
service_id
string
Only documents linked to this service.
​
assessment_id
string
Only documents attached to this assessment.
​
limit
integer
Page size, 1–200 (default 50).
​
offset
integer
Pagination offset (default 0).
cURL
curl "https://sandbox.api.coverbase.app/v1/documents?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162&limit=50" \
  -H "Authorization: Bearer ak_live_xxx"

{
  "data": [ { "id": "cbvdoc_...", "vendor_id": "cbvndr_...", "name": "ACME SOC 2 Type II", "...": "..." } ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
Get a document

​
method
GET
GET /v1/documents/{document_id}
Returns a single document’s metadata and links, or 404 document_not_found.
cURL
curl "https://sandbox.api.coverbase.app/v1/documents/cbvdoc_2f1c9a7b6d5e4f3a2b1c0d9e8f7a6b5c" \
  -H "Authorization: Bearer ak_live_xxx"

​
Download a document

​
method
GET
GET /v1/documents/{document_id}/download
Returns a short-lived (one hour) presigned URL for the document’s file. Follow the returned url with a plain GET (no Authorization header) to fetch the bytes — it serves the file as an attachment with the original filename.
cURL
# 1. Get the presigned URL
curl "https://sandbox.api.coverbase.app/v1/documents/cbvdoc_2f1c.../download" \
  -H "Authorization: Bearer ak_live_xxx"

# 2. Follow it to download the file
curl -L -o acme_soc2.pdf "https://<presigned-s3-url>"

{
  "url": "https://<bucket>.s3.amazonaws.com/<key>?X-Amz-Signature=...",
  "filename": "ACME SOC 2 Type II.pdf",
  "expires_in": 3600
}

​
Update a document

​
method
PATCH
PATCH /v1/documents/{document_id}
Updates the name, type, and links. All fields are optional; omitted fields are left unchanged. Supplying a list for service_ids / assessment_ids replaces the existing set (pass [] to clear it).
​
name
string
Replacement display name.
​
document_type
string
Replacement document type slug.
​
service_ids
string[]
Replaces the set of linked services.
​
assessment_ids
string[]
Replaces the set of attached assessments.
cURL
curl -X PATCH "https://sandbox.api.coverbase.app/v1/documents/cbvdoc_2f1c..." \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "service_ids": ["cbsvc_1a2b", "cbsvc_3c4d"], "assessment_ids": ["cbqsrw_9f8e"] }'

​
Archive a document

​
method
DELETE
DELETE /v1/documents/{document_id}
Archives (soft-deletes) the document. The underlying record is retained for audit but no longer appears in list results.
cURL
curl -X DELETE "https://sandbox.api.coverbase.app/v1/documents/cbvdoc_2f1c..." \
  -H "Authorization: Bearer ak_live_xxx"

{ "id": "cbvdoc_2f1c...", "is_archived": true, "archived_at": 1749427200 }

​
Attaching documents to assessments

There are two ways to link a document to an assessment:
  1. At upload time — pass assessment_ids to POST /v1/documents (or service_ids to attach to services).
  2. At assessment-create time — upload the document first, then pass its ID in supporting_document_ids when calling POST /v1/assessments.
  3. Later — PATCH /v1/documents/{document_id} with assessment_ids / service_ids.

​
Errors

StatuscodeWhen
400unsupported_file_typeThe file extension is not in the allowlist.
413file_too_largeThe file exceeds the 100 MiB limit.
422invalid_document_typedocument_type is not a known slug.
404vendor_not_foundThe vendor_id does not exist in your org.
404document_not_foundThe document does not exist in your org.
404assessment_not_foundA filtered assessment_id does not exist.
409document_not_readyThe document has no stored file to download yet.
See the error envelope for the response shape.