Evidence API Overview

Base URL

Production: https://api.softquantus.com/api/v2/evidence
Sandbox:    https://sandbox.softquantus.com/api/v2/evidence

Authentication

All requests require Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.softquantus.com/api/v2/evidence/...

---

Endpoints Summary

Evidence Management

Method	Endpoint	Description
GET	/{bundle_id}	Get evidence bundle
POST	/generate	Generate evidence for job
GET	/list	List your evidence bundles
DELETE	/{bundle_id}	Delete bundle (Enterprise)

Verification

Method	Endpoint	Description
POST	/verify	Verify a bundle
POST	/verify/batch	Verify multiple bundles

Export

Method	Endpoint	Description
GET	/{bundle_id}/export	Export in various formats

---

Quick Examples

Get Evidence Bundle

curl https://api.softquantus.com/api/v2/evidence/ev_abc123 \
  -H "Authorization: Bearer $QCOS_API_KEY"

Response:

{
  "success": true,
  "data": {
    "bundle_id": "ev_abc123",
    "version": "3.0",
    "type": "optimization",
    "created_at": "2026-02-06T12:00:00Z",
    "execution": {
      "job_id": "job_xyz789",
      "circuit_hash": "sha3-256:abc123...",
      "backend": "ionq_simulator",
      "shots": 1024,
      "results_hash": "sha3-256:def456..."
    },
    "chain": {
      "previous_bundle": "ev_abc122",
      "sequence": 1523,
      "merkle_root": "sha3-256:ghi789..."
    },
    "signatures": {
      "algorithm": "ML-DSA-65",
      "public_key_id": "pk_xyz789",
      "signature": "base64:..."
    },
    "timestamp_proof": {
      "authority": "softquantus-tsa",
      "timestamp": "2026-02-06T12:00:00.123456Z",
      "token": "base64:..."
    }
  }
}

Verify Evidence

curl -X POST https://api.softquantus.com/api/v2/evidence/verify \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "ev_abc123"}'

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "bundle_id": "ev_abc123",
    "verified_at": "2026-02-06T12:05:00Z",
    "checks": {
      "signature": "valid",
      "circuit_hash": "valid",
      "results_hash": "valid",
      "timestamp": "valid",
      "chain": "valid"
    },
    "verification_time_ms": 8
  }
}

Generate Evidence

curl -X POST https://api.softquantus.com/api/v2/evidence/generate \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job_xyz789",
    "include_circuit": true,
    "include_results": true,
    "pqc_algorithm": "ML-DSA-65"
  }'

Response:

{
  "success": true,
  "data": {
    "bundle_id": "ev_new123",
    "job_id": "job_xyz789",
    "created_at": "2026-02-06T12:10:00Z"
  }
}

Export Evidence

curl https://api.softquantus.com/api/v2/evidence/ev_abc123/export?format=pdf \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -o evidence_report.pdf

Query Parameters:

Parameter	Values	Description
format	json, pdf, cbor	Export format

---

Bundle Schema

{
  "bundle_id": "string",
  "version": "3.0",
  "type": "optimization | position | timing | network",
  "created_at": "ISO 8601",

  "execution": {
    "job_id": "string",
    "circuit_hash": "sha3-256:hex",
    "backend": "string",
    "shots": "integer",
    "results_hash": "sha3-256:hex",
    "start_time": "ISO 8601",
    "end_time": "ISO 8601"
  },

  "chain": {
    "previous_bundle": "string | null",
    "sequence": "integer",
    "merkle_root": "sha3-256:hex"
  },

  "signatures": {
    "algorithm": "ML-DSA-65",
    "public_key_id": "string",
    "signature": "base64"
  },

  "timestamp_proof": {
    "authority": "string",
    "timestamp": "ISO 8601",
    "token": "base64"
  }
}

---

Verification Checks

Check	Description
signature	PQC signature is valid
circuit_hash	Input circuit matches hash
results_hash	Output results match hash
timestamp	TSA token is valid
chain	Chain links are correct

---

Error Codes

Code	HTTP	Description
BUNDLE_NOT_FOUND	404	Bundle ID not found
VERIFICATION_FAILED	400	Bundle failed verification
JOB_NOT_FOUND	404	Job ID for generation not found
EVIDENCE_DISABLED	400	Evidence was not enabled for job
EXPIRED	410	Bundle past retention period
UNAUTHORIZED	401	Invalid API key

---

Webhooks

Subscribe to evidence events:

curl -X POST https://api.softquantus.com/api/v2/webhooks \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "evidence.created",
    "url": "https://your-app.com/webhook"
  }'

Events:

• evidence.created - New bundle generated
• evidence.verified - Bundle verified
• evidence.exported - Bundle exported

---

© 2024-2026 SoftQuantus Innovative OÜ