Developers

Documentation

AuditProven Shield API Reference

Integrate AuditProven Shield into your existing compliance workflow, GRC platform, or CI/CD pipeline.

Base URL

https://api.auditproven.com/v1

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer vc_live_xxxxxxxxxxxxxxxxxxxx

API keys are generated in the AuditProven Shield dashboard under Settings > API Keys.

Endpoints

Upload Documents

POST /assessments/upload
Content-Type: multipart/form-data

Upload one or more policy documents for assessment. Accepted formats: PDF, DOCX, TXT, MD. Maximum file size: 50 MB per file, 200 MB per assessment.

Request:

files[] — one or more document files
assessment_name — optional name for the assessment

Response:

{
  "assessment_id": "asmnt_7f3a2b1c",
  "documents": [
    {"name": "security_policy.pdf", "sections": 12, "pages": 20}
  ],
  "status": "uploaded"
}

Run Assessment

POST /assessments/{assessment_id}/analyze
Content-Type: application/json

Request Body:

{
  "framework": "soc2",
  "options": {
    "include_evidence_matrix": true,
    "include_remediation": true,
    "multi_framework": ["soc2", "iso27001"]
  }
}

Response:

{
  "assessment_id": "asmnt_7f3a2b1c",
  "status": "processing",
  "estimated_seconds": 45
}

Get Assessment Status

GET /assessments/{assessment_id}/status

Response:

{
  "assessment_id": "asmnt_7f3a2b1c",
  "status": "complete",
  "progress": {
    "parsing": "complete",
    "extraction": "complete",
    "classification": "complete",
    "mapping": "complete",
    "gap_analysis": "complete",
    "narrative_generation": "complete",
    "report_composition": "complete"
  }
}

Get Report

GET /assessments/{assessment_id}/report
Accept: application/json

Returns the complete compliance report as JSON. For other formats:

Accept: application/pdf — PDF download
Accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document — DOCX download
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — XLSX (evidence matrix only)

Get Provenance

GET /assessments/{assessment_id}/provenance

Returns the complete provenance chain including all claim hashes and the Merkle root.

Verify Claim

POST /assessments/{assessment_id}/verify
Content-Type: application/json

Request Body:

{
  "claim_hash": "a1b2c3d4e5f6..."
}

Response:

{
  "verified": true,
  "source_document": "security_policy.pdf",
  "source_section": "3.2 Access Control",
  "source_page": 7,
  "requirement_id": "dL02.cc6_1",
  "merkle_path": ["hash1", "hash2", "hash3"],
  "merkle_root": "root_hash"
}

List Frameworks

GET /frameworks

Returns all supported frameworks with requirement counts and version information.

List Assessments

GET /assessments?page=1&per_page=20

Returns paginated list of past assessments with status and summary statistics.

Delete Assessment

DELETE /assessments/{assessment_id}

Permanently deletes the assessment, report, and all associated provenance data.

Rate Limits

Plan	Requests per minute	Assessments per month
Professional	60	Unlimited
Enterprise	300	Unlimited

Error Codes

Code	Meaning
400	Invalid request (malformed JSON, unsupported file type)
401	Invalid or missing API key
403	Insufficient plan for requested feature
404	Assessment not found
413	File too large
429	Rate limit exceeded
500	Internal server error (contact support)

SDKs

Official SDKs are in development for Python and TypeScript. In the meantime, any HTTP client works — the API accepts standard REST calls with JSON payloads.

Webhooks

Enterprise plans can configure webhook URLs to receive notifications when assessments complete:

{
  "event": "assessment.complete",
  "assessment_id": "asmnt_7f3a2b1c",
  "framework": "soc2",
  "summary": {
    "total_requirements": 60,
    "addressed": 48,
    "gaps": 12
  }
}