Hub API

The Hub API is the primary read/write surface for the canonical org-memory store.

Endpoint

https://api.claresia.com/api/v1/hub

(or https://api.{tenant_slug}.claresia.cloud/api/v1/hub for Mode C BYOC)

Query records

GET /api/v1/hub/records?record_type=output&skill_id=gatespic.incident-postmortem&limit=50
Authorization: Bearer <jwt>
X-Claresia-Tenant: dainese

Supported query parameters:

Param	Type	Notes
record_type	enum	One of the 6 types
record_id	string	Single-record lookup
skill_id	string	Filter by skill (output / telemetry only)
archetype_id	string
user_id	string
created_by	string
created_at__gte	RFC3339
created_at__lt	RFC3339
event_kind	string	governance_event filter
limit	int	Max 1000, default 50
cursor	string	Pagination
sort	string	created_at (default), -created_at, cost_usd_estimate, -cost_usd_estimate
verify	bool	If true, verify provenance + cosign on each returned record
include_purged	bool	Default false

Response:

{
  "records": [
    { /* Hub record */ },
    { /* Hub record */ }
  ],
  "next_cursor": "Y3Vyc29yOjAxOTMzYThm...",
  "verification_summary": {
    "checked": 50,
    "verified": 50,
    "tampered": 0,
    "cosign_invalid": 0
  }
}

Get a single record

GET /api/v1/hub/records/01933a8f-...?verify=true

Write a record

POST /api/v1/hub/records
Content-Type: application/json

{
  "record_type": "decision",
  "decision_id": "DEC-2026-04-119",
  "decision_subject": "approve_dpia",
  "decision_outcome": "approved",
  "decision_rationale": "All technical and organizational measures in place.",
  "decision_actor_role": "compliance_officer",
  "related_records": ["01933a8f-..."]
}

Server fills in:

• record_id (uuid v7)
• tenant_id (from X-Claresia-Tenant)
• created_at (server time)
• created_by (from JWT subject)
• provenance_hash (computed)
• provenance_cosign (computed)
• schema_version (current)

Response:

HTTP/1.1 201 Created
Location: /api/v1/hub/records/01933a91-...

{
  "record_id": "01933a91-...",
  "provenance_hash": "kT8Zw...",
  "provenance_cosign": "Vp3X..."
}

Bulk export (for legal / audit / migration)

POST /api/v1/hub/records:export
Content-Type: application/json

{
  "filter": {
    "tenant_id": "dainese",
    "record_type": ["governance_event"],
    "created_at__gte": "2026-01-01T00:00:00Z"
  },
  "format": "jsonl",
  "verify": true,
  "include_provenance": true
}

Response is 202 Accepted with a Location header to a job:

HTTP/1.1 202 Accepted
Location: /api/v1/hub/exports/exp_2H8j4...

{
  "job_id": "exp_2H8j4...",
  "status": "queued",
  "estimated_completion_ts": "2026-05-03T15:00:00Z"
}

Poll the job:

GET /api/v1/hub/exports/exp_2H8j4...

When status: completed, fetch the signed download URL (valid 24h) from download_url. Format options: jsonl, csv, parquet.

Soft-delete

DELETE /api/v1/hub/records/01933a91-...?reason=user-request

Marks is_purged = true. 30-day recovery buffer before hard-delete.

governance_event records cannot be soft-deleted unless the requester has the hub:purge scope and an active legal-hold release on the record.

Hub record relationships

Records link via related_records[] (array of UUIDs). Common patterns:

• output → artifact (skill produced an artifact)
• decision → output (decision was made on top of a skill output)
• governance_event → output (audit event mentions a specific skill output)
• output → output (chain of dependent skill calls)

Walk the graph:

GET /api/v1/hub/records/01933a8f-.../related?depth=2

Returns the seed record + records up to 2 hops away.

Provenance verification

POST /api/v1/hub/records/01933a8f-.../verify

Response:

{
  "verified": true,
  "checks": {
    "provenance_hash_matches": true,
    "provenance_cosign_valid": true,
    "schema_version_supported": true,
    "no_active_legal_hold_violation": true
  }
}

If verified: false, a governance_event of kind hub.tamper_detected is auto-emitted (idempotent — once per record per UTC day).

Hub Browser

The same data is browsable in a web UI at https://hub.{tenant_slug}.claresia.com (Mode A/B) or your Mode C equivalent. Same RBAC as the API.

Errors

HTTP	Meaning
400	Validation failed
401	Auth failed
403	Scope insufficient or tenant mismatch
404	Record not found / purged beyond recovery buffer
409	Concurrent modification (rare; retry with fresh ETag)
422	Record violates retention or hold rules
429	Rate limit

Reference

• Hub schema
• Provenance + Audit
• Retention
• Storage backends