Docs

API Reference

Everything the SDKs do under the hood. Base URL: https://api.softechlog.com — all endpoints are JSON over HTTPS.

Authentication

Three credentials, each with a deliberately narrow job:

# Server-side — secret key (ingest + read + export + stats + mint feed tokens)
Authorization: Bearer stl_sk_xxxxxxxxxxxx

# Browser — feed token (read-only, pinned to an actor and/or a tenant; minted with a secret key)
Authorization: Bearer stl_ft_xxxxxxxxxxxx

# Browser — public key (auto-capture ONLY; travels in the batch JSON body, not a header)
{ "public_key": "stl_pk_xxxxxxxxxxxx", "events": [ … ] }

Customer sites can call the batch endpoint and read with feed tokens from any origin (CORS Allow-Origin: *, no credentials); everything else is restricted to the dashboard's origins.

Events

Ingest an event

POST /v1/events
Content-Type: application/json
Authorization: Bearer stl_sk_xxxxxxxxxxxx

{
  "actor":     { "id": "user_123", "name": "Ari", "email": "ari@acme.co", "avatar_url": null },
  "action":    "member.invited",
  "tenant_id": "org_acme",
  "target":    { "type": "workspace", "id": "ws_abc", "name": "Acme" },
  "metadata":  { "role": "admin" },
  "capture_mode": "manual",
  "session_id": "0f6d5c1e-…",
  "timestamp": "2026-08-17T14:09:31Z",
  "context":   { "ip_address": "203.0.113.4", "user_agent": "Mozilla/5.0 …" }
}

→ 201 { "id": "9b2f0f5e-4c1a-4e7b-9d3f-2a6c8e1b7f10", "queued_at": "2026-08-17T14:09:31.412Z",
        "leaf_hash": "5d1c…64 hex…" }

Send an Idempotency-Key header (any unique string ≤ 128 chars, e.g. a UUID) and reuse it when you retry: a repeat within 24 hours returns the original event with 200 and Idempotent-Replayed: true instead of storing a duplicate. The official SDKs do this automatically.

The response's leaf_hash is the event's integrity leaf — the SHA-256 that the next checkpoint seals (see Tamper evidence). Store it for high-value events: it is your receipt for the minutes before the event is sealed. Idempotent replays return the same value.

Events returned by GET /v1/events and the actor history include erasure_id: null, or the id of the erasure request that last redacted the row. Exports (CSV and JSON) append an erasure_id column as the last column, so positional parsers keep working.

Batch ingest (auto-capture)

POST /v1/events/batch
Content-Type: text/plain          # no CORS preflight; the body is still JSON

{
  "public_key": "stl_pk_xxxxxxxxxxxx",
  "events": [
    {
      "action": "ui.page_viewed",
      "actor": { "id": "user_123" },
      "metadata": { "url": "https://app.acme.co/settings", "title": "Settings" },
      "capture_mode": "auto",
      "session_id": "0f6d5c1e-…",
      "occurred_at": "2026-08-17T14:09:31Z"
    }
    /* 1 – 100 events */
  ]
}

→ 201 { "accepted": 1, "rejected": 0 }

Each item accepts action (required), actor, target, metadata, session_id, and occurred_at. Everything a public key sends is stored as capture_mode: "auto" (a capture_mode field is ignored), occurred_at is clamped to the server's clock, and actor identity fields only fill in blanks — they never overwrite what the secret key recorded. tenant_id is ignored here: anyone can read a public key from your page source, so only your server may place events in an account's audit trail. Items with an invalid or reserved (softechlog.*) action, oversized metadata, non-finite metadata numbers, or an occurred_at older than a year are counted in rejected; the rest are stored. The whole batch is refused with 402 if it would exceed your monthly cap.

Feed tokens

POST /v1/feed-tokens
Authorization: Bearer stl_sk_xxxxxxxxxxxx

{ "actor_id": "user_123", "ttl_seconds": 3600 }          # one user
{ "tenant_id": "org_acme", "ttl_seconds": 3600 }         # a whole account

→ 201 { "token": "stl_ft_…", "expires_at": "2026-08-17T15:09:31Z", "actor_id": "user_123", "tenant_id": null }

Actors

Sessions

Sessions are created automatically from the session_id on any event — auto-capture always sends one.

Stats

Erasures

Erase one of your users' personal data (GDPR Art. 17). What each mode keeps and removes is spelled out in Erasure. Secret key, or the dashboard; public keys and feed tokens get 403.

POST /v1/erasures
Authorization: Bearer stl_sk_xxxxxxxxxxxx
Idempotency-Key: 5a0c…                     # optional, 24 h replay

{ "actor_id": "user_123", "mode": "delete", "target_types": ["user"], "reference": "DSR-2026-0142" }

→ 201 (finished) or 202 (finishing in the background)
{
  "id": "7c1e…", "status": "completed", "mode": "delete", "target_types": ["user"],
  "reference": "DSR-2026-0142", "requested_via": "api_key", "requested_by": "stl_sk_ab12cd34",
  "requested_at": "2026-09-26T10:00:00.123456+00:00", "started_at": "…", "completed_at": "…",
  "actor_found": true,
  "counts": { "events_deleted": 212, "events_redacted": 0, "target_refs_redacted": 3, "sessions_deleted": 9 },
  "affected_count": 215, "affected_hash": "64 hex", "evidence_event_id": "…", "error": null
}

The Erasure object is the same in every response and never contains the user's id. actor_found is null until completion; affected_hash (SHA-256 over the affected event ids and codes) and evidence_event_id (the sealed softechlog.actor.erased event) are set on completion; error is an exception class name when failed.

Tamper evidence

Checkpoints, keys and verification for the tamper-evident log. All integrity timestamps are UTC strings with exactly six fractional digits and a trailing Z (the exact strings that were signed); all hashes are lowercase hex.

GET /v1/integrity/verify?pin=41:9f2c…&expected_retention_days=90
Authorization: Bearer stl_sk_xxxxxxxxxxxx

→ 200
{
  "ok": true, "project_id": "…", "from_seq": 1, "to_seq": 42, "head_seq": 42, "head_hash": "64 hex",
  "next_from_seq": null, "checkpoints_checked": 42, "leaves_checked": 12000,
  "events": { "verified": 11900, "redacted": 12, "expired": 80, "erased": 8, "pending_seal": 3 },
  "retention_cutoff": "2026-06-28T00:00:00.000000Z", "retention_days": 90,
  "failures": [], "failures_truncated": false,
  "warnings": [], "warnings_truncated": false,
  "verified_at": "2026-09-26T10:00:00.000000Z"
}

Failure kinds: header_hash_mismatch, bad_signature, unknown_key, seq_gap, chain_break, retention_cutoff_invalid, retention_below_expected, pinned_mismatch, pinned_missing, leaves_missing, leaves_length_mismatch, leaves_hash_mismatch, event_modified, event_missing, redaction_unexplained, unexpected_event, event_unsealed, erasure_evidence_missing, erasure_evidence_mismatch. Warning kinds: retention_days_changed, erasure_in_progress, erasure_failed, sealing_stalled, sealing_paused, retention_cutoff_unsigned, no_checkpoints. Each list is capped at 100 entries (failures_truncated / warnings_truncated).

Errors & limits

Every error is JSON with a detail and a request_id you can quote to support:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "detail": "Rate limit exceeded: 1000 requests per 60s.", "request_id": "3f9c…" }