API & SDK Specification

Integrate Sigigo into your applications. Emit canonicalized events, verify cryptographic proofs, and export evidence packs programmatically. See platform guides for OpenAI, OpenRouter, Vercel AI, LangChain, and more, or review platform architecture.

Event Schema

Canonicalized JSON object with required and optional fields:

event-schema.json
{
  "event_id": "UUID or hash",
  "timestamp": "ISO8601",
  "actor": "user, service, agent, or system",
  "action": "string",
  "target": "object or identifier",
  "metadata": "object, optional",
  "evidence_type": "e.g., ai_decision, workflow, security, compliance, data_act",
  "payload_hash": "hash of sensitive data, not raw data"
}

EU AI Act event types (evidence_type: "ai_act")

For Article 12 high-risk AI logging, use action values prefixed with ai_act. — e.g. ai_act.input_received, ai_act.output_generated, ai_act.human_review_completed. For Article 50 transparency (August 2026), add ai_act.transparency_disclosure at the disclosure boundary. Prefer commitments over raw prompts. Field maps: Article 12 guide, Article 50 guide.

Data Act event types (evidence_type: "data_act")

For EU Data Act workflows (IoT access, B2B sharing, cloud switching), use action values prefixed with data_act. — e.g. data_act.share_initiated, data_act.access_granted, data_act.cloud_switch_verified. Full catalog and example payloads: 14-eu-data-act-analysis.md.

REST Endpoints

POST/v1/events
Submit Event

Body: single event. Returns: event id, receipt, status

POST/v1/exports
Export evidence pack

Body: batch_id or event_ids. Returns: self-verifying evidence pack JSON

POST/v1/verify
Verify evidence pack

Body: full evidence pack. Returns: PASS/FAIL report with per-check details (same engine as npx @sigigo/verify)

GET/verify
Public verify portal

Unauthenticated web UI — paste or upload a pack for offline verification

SDK Expectations

  • Canonicalization and hashing performed locally
  • Signing with customer or service keys
  • Idempotency for event submission
  • Error handling with clear codes and messages
  • Language support: Node.js, Python (MVP), others to follow

Authentication

  • API keys (initially)
  • OAuth and service accounts (future)
  • All endpoints require authentication

Idempotency

  • Idempotency keys supported for event and batch submissions
  • Duplicate submissions return the same proof and status

Error Handling

  • Standardized error codes and messages
  • Clear feedback for schema validation, authentication, and proof failures