SnapOS API Documentation (v1)

This page summarises the external API endpoints of SnapOS and complements them with additional descriptions about authentication, error handling and SnapOS’s unique features. It can be embedded as a standalone HTML file on your website.

Overview

SnapOS is an audit‑capable semantic framework that detects, measures and stabilises semantic drift. The API makes it possible to evaluate semantic units (SnapScore), retrieve forecast clusters, view audit trails and perform ethics as well as re‑entry checks. Unlike classical frameworks, SnapOS uses deep semantic metrics and a normative ethics runtime to guarantee trust and reproducibility.

Authentication

All endpoints require a valid bearer token. Tokens are issued via the SnapOS portal or on request via compliance@snapos.org. Example of the required headers:

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

If the token is missing or invalid, the API returns a 401 Unauthorized status.

1. POST /snapscore  – Calculate SnapScore

Calculates the SnapScore of a submitted semantic unit. The SnapScore measures semantic stability and is unique compared with traditional classification metrics.

Request

{
  "text": "ORD-O stabilises semantic drift.",
  "agent_id": "agent-9281",
  "origin_id": null
}

Response

{
  "id": "snap-uuid",
  "SnapScore": 76,
  "state": "active",
  "type": "operator",
  "semantic_topics": ["ORD-O"],
  "delta_score": 0,
  "omega_ready": true,
  "sigma_valid": true,
  "audit_id": "audit-uuid"
}

Status codes: 200 OK – score calculated; 400 Bad Request – missing or invalid parameters; 401 Unauthorized – token missing.

2. GET /forecast/cluster/:id  – Query forecast cluster

Returns metadata for a forecast cluster. SnapOS groups snapshots into forecast clusters to detect semantic drift trends – a feature rarely present in other audit frameworks.

{
  "cluster_id": "fc-01a",
  "mean_SnapScore": 72.3,
  "semantic_topics": ["regulation", "genomics"],
  "drift_vector": { "D": 0.14, "phi": 0.05 },
  "orbit_profile": "spiral",
  "ethics_flag": true
}

Status codes: 200 OK – data found; 404 Not Found – cluster not found.

3. GET /audit/:id  – Download audit trail

Returns the full audit trail for a snapshot. The audit trail includes timestamps, SnapScore, ethics trace and the drift path.

{
  "audit_id": "audit-uuid",
  "timestamp": "2025-11-08T12:33Z",
  "SnapScore": 76,
  "ethics_trace": {
    "compliance_level": "moderate",
    "trace_id": "eth-trace-38f"
  },
  "drift_path": ["init", "stabilised", "emergent"],
  "reentry_ready": true
}

4. Ethics & Re‑entry (W8–W12)

GET /ethics/verify/:snapshot_id

Returns the ethics assessment and a decision matrix for the snapshot. SnapOS integrates E09 – the ethics runtime check – to ensure normative requirements within semantic audits.

POST /reentry/check

Checks whether a snapshot is ready for re‑entry (return to the audit chain). The response includes the target zone and feedback cycle.

5. Operators

GET /operator/list

Lists all active SnapOperators – modules such as W₁ through W₂₃, SnapCut and TrueClaim².

GET /operator/:id

Returns details of a specific operator: description, audit status and versioning.

6. MetaAuditShell & Reproducibility

Allows you to submit multiple snapshots or full audit trails for system‑wide evaluation. The MetaAuditShell ensures the reproducibility of your results and is part of SnapOS’s unique audit approach.

POST /meta-audit/run

The request body should contain a list of snapshots or a complete trace. The response returns aggregated audit results.

7. System metadata

Additional endpoints:

• GET /status – system status, last commits, active modules
• GET /version – current API version and backend version

Note on uniqueness

If you have questions or need additional functions (for example, W₁–W₂₃ documentation, ethics runtime details or SnapMemoryBank) please visit the corresponding pages or contact us at info@snapos.org.