Protocol Specification

ContextSync v0.1

The full HTTP surface for the ContextSync protocol. Every endpoint this dashboard hits is documented here, and the JSON shapes below are the canonical wire format for artifacts, change events, permissions, and provenance records.

Artifact URI

Every artifact has a content-addressed URI of the form:

ctx://{org}/{domain}/{id}

The URI is stable across edits, renames, and moves. Wildcards are supported in permission and subscription patterns: * matches a single segment, ** matches across slashes.

Permission model

Permissions are tuples over (actor | agent_class, artifact_pattern, operations). The model is default-deny: no grant means no access.

read fetch artifact content and history

write create or update versions

suggest propose changes for review

approve approve suggested changes

admin all operations

Endpoints

Organized by resource. All responses are JSON unless otherwise noted.

Artifacts

POST	/artifacts	Create an artifact at version 1
GET	/artifacts?uri=&version=	Fetch an artifact by URI (optional version)
PUT	/artifacts?uri=	Create a new version
DELETE	/artifacts?uri=	Soft-delete an artifact
GET	/artifacts/history?uri=	Full version history
GET	/artifacts/diff?uri=&from=&to=	Line-diff between two versions
GET	/artifacts/list?org=&domain=	List artifacts (read-permission filtered)

Actors

POST	/actors	Create a human or agent actor
GET	/actors	List all actors
GET	/actors/:id	Fetch a single actor

Changes

GET	/changes?since=&actor=&limit=	Global change feed
GET	/domains/:domain/changes?since=	Change feed scoped to a domain

Subscriptions (SSE)

POST	/subscriptions	Create a subscription on a URI pattern
GET	/subscriptions/stream?pattern=	One-shot ephemeral subscription + SSE feed
GET	/subscriptions/:id/feed	Persistent SSE feed for an existing subscription
DELETE	/subscriptions/:id	Remove a subscription

Permissions

POST	/permissions	Grant ops on a pattern (actor or class)
GET	/permissions?actor_id=&agent_class=	List grants
GET	/permissions/explain?actor_id=&uri=&op=	Explain a permission decision

Provenance

GET

/provenance?artifact=&actor=&limit=

Read the audit log

Stats

GET	/stats	Aggregate server counts
GET	/stats/orgs	Per-organization counts
GET	/stats/domains	Per-(org,domain) counts

Artifact object

{
  "uri":          "ctx://acme-capital/compliance/data-retention-policy",
  "name":         "Data Retention Policy",
  "org":          "acme-capital",
  "domain":       "compliance",
  "content_type": "text/markdown",
  "head_version": 3,
  "created_at":   "2026-04-11T22:50:43.750Z",
  "updated_at":   "2026-04-11T22:51:21.590Z"
}

Change event

{
  "event_id":         "evt_a1b2c3",
  "event_type":       "artifact.updated",
  "artifact_uri":     "ctx://acme-capital/compliance/data-retention-policy",
  "version":          3,
  "previous_version": 2,
  "author_id":        "human-alex-chen",
  "summary":          "align with new SEC rule",
  "diff_json":        { "stats": { "added_lines": 2, "removed_lines": 2 } },
  "created_at":       "2026-04-11T22:50:44.104Z"
}

Permission tuple

{
  "actor_id":         null,
  "agent_class":      "compliance-monitor",
  "artifact_pattern": "ctx://acme-capital/compliance/*",
  "operations":       ["read", "suggest"]
}

Provenance record

{
  "prov_id":         "prov_9f8e7d",
  "actor_id":        "agent-acme-compliance-monitor",
  "operation":       "read",
  "artifact_uri":    "ctx://acme-capital/compliance/data-retention-policy",
  "version_touched": 3,
  "downstream_uri":  null,
  "created_at":      "2026-04-11T22:51:02.003Z"
}