API Reference

REST API endpoints for integrating with ChainShield programmatically. 38 operations, generated from the live OpenAPI specification.

Authentication

API Key: Create an API key at Settings > API Keys. Include it in the Authorization header:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Each endpoint below lists the API key scope it requires. Endpoints badged Session auth only require an authenticated browser session (not an API key) rather than a scope, while endpoints badged No auth required are public health probes callable without any credentials.

All API requests are rate-limited. See the X-RateLimit-Remaining response header for your current quota.

Assessments

5 endpoints

GET
/api/v1/assessments

List vendor risk assessments in the org

assessments:read
POST
/api/v1/assessments

Create a vendor assessment (starts in DRAFT status)

assessments:write
DELETE
/api/v1/assessments/{id}

Delete an assessment

assessments:write
GET
/api/v1/assessments/{id}

Get a single assessment

assessments:read
PUT
/api/v1/assessments/{id}

Update an assessment (title, status, due_date, responses, questions)

assessments:write

Assets

3 endpoints

DELETE
/api/v1/assets/discovery

Permanently delete a REJECTED asset (superuser/MSP-admin only)

assets:write
GET
/api/v1/assets/discovery

List discovered assets for a vendor (paginated, filterable by type)

assets:read
PATCH
/api/v1/assets/discovery

Confirm, reject, or update status for a batch of assets (superuser/MSP-admin for confirm/reject)

assets:write

Compliance

1 endpoint

GET
/api/v1/compliance

List compliance control status rows for the org

compliance:read

CVE

3 endpoints

GET
/api/v1/cve

List/search CVEs affecting the org's vendor portfolio

vendors:read
GET
/api/v1/cve/{id}

Get a single CVE from the vulnerability catalogue

vendors:read
GET
/api/v1/cve/{id}/affected-vendors

List vendors in the org affected by a given CVE

vendors:read

Findings

2 endpoints

GET
/api/v1/findings

List findings across the org (lightweight columns)

findings:read
PUT
/api/v1/findings

Update a single finding's status/notes/assignment

findings:write

MSPs

2 endpoints

GET
/api/v1/msps

List MSPs visible to the caller (all for superuser, own MSP otherwise; session auth only)

Session auth only
POST
/api/v1/msps

Create a new MSP (system-tier superuser; session auth only)

Session auth only

System

5 endpoints

GET
/api/v1/health

Service health — DB connectivity + event-bus circuit breaker (verbose detail requires superuser/cron)

No auth required
GET
/api/v1/health/live

Liveness probe — process is up, no DB check

No auth required
GET
/api/v1/health/ready

Readiness probe (re-exports /api/v1/health's handler verbatim)

No auth required
GET
/api/v1/liveness

Liveness probe — no DB check, no project-ref disclosure

No auth required
GET
/api/v1/readiness

Readiness probe — DB connectivity check

No auth required

Users

5 endpoints

DELETE
/api/v1/users

Remove a member or revoke a pending invitation (session auth only)

Session auth only
GET
/api/v1/users

List org members and pending invitations (session auth only)

Session auth only
PATCH
/api/v1/users

Update a member's role, active status, or granular permissions (session auth only)

Session auth only
POST
/api/v1/users

Invite a user to the organisation (session auth only)

Session auth only
PUT
/api/v1/users

Resend a pending invitation (session auth only)

Session auth only

Vendors

12 endpoints

DELETE
/api/v1/vendors

Remove a vendor from the organisation (unlink, not global delete)

vendors:write
GET
/api/v1/vendors

List vendors in the org (or MSP cross-org / superuser catalogue)

vendors:read
PATCH
/api/v1/vendors

Update org-level vendor fields (lifecycle_stage, tier, business_criticality)

vendors:write
POST
/api/v1/vendors

Add a vendor to the organisation (creates the global vendor row if new)

vendors:write
DELETE
/api/v1/vendors/{id}

Unlink vendor from the org, or MSP-wide bulk unlink with ?scope=msp

vendors:write
GET
/api/v1/vendors/{id}

Get vendor detail with embedded findings, assessments, and risk analysis

vendors:read
PATCH
/api/v1/vendors/{id}

Update vendor + org-vendor overlay fields in one call (superuser or org admin)

vendors:write
PUT
/api/v1/vendors/{id}

Replace vendor global fields (name, industry_sector — superuser only; silently dropped otherwise)

vendors:write
GET
/api/v1/vendors/{id}/msp-impact

Count of MSP customer orgs linked to this vendor (MSP admin only)

vendors:read
PATCH
/api/v1/vendors/{id}/resource-urls

Set a curated resource URL (trust centre, security.txt, etc.) for a vendor

vendors:write
GET
/api/v1/vendors/{id}/technologies/{techId}

Technology detail with catalogue enrichment, version history, linked assets, and findings

vendors:read
GET
/api/v1/vendors/{id}/vulnerabilities

List CVE matches against this vendor's discovered technologies/assets

vendors:read

OpenAPI Specification

Download the machine-readable OpenAPI specification for use with tools like Swagger UI, Postman, or code generators.

Download OpenAPI spec (JSON)
Manage API KeysOpenAPI SpecHealth Check