HTTP API

Authenticate, upload bytes, publish a version, and read shared history.

Use Authorization: Bearer $KNOWLEDGE_TOKEN against the same HTTPS origin that issued the credential. HTTP is allowed only for loopback development. The CLI refuses redirects, avoiding credential forwarding to a different destination. Browser session authentication continues to work on these same resources.

Request	Result
`GET /api/projects/:id/commits?at=`	`{version}` for current main, or null for an empty project
`GET /api/projects/:id/commits?at=VERSION`	Immutable snapshot, including files and parent ID
`GET /api/projects/:id/commits`	`{commits}` ordered by parent ancestry, newest first
`GET /api/projects/:id/files?at=VERSION&path=PATH`	Exact file bytes; query parameters must be URL encoded
`POST /api/projects/:id/files`	Upload raw bytes with URL-encoded `x-file-path` and `content-type`; returns path/hash/size/mediaType plus upload proof for bearer callers
`POST /api/projects/:id/commits`	Publish the JSON request below and return the immutable version receipt
`GET /api/projects/:id/events`	SSE current-head notifications; reconnect and reread after disconnect
`POST /api/projects/:id/access`	Browser-only, same-origin credential issuance; used by `/cli`

{
  "expectedHead": "VERSION_USED_AS_BASE",
  "operationId": "client-generated-unique-id",
  "summary": "Add research",
  "changes": [{
    "path": "notes.md",
    "hash": "SHA256_RETURNED_BY_UPLOAD",
    "size": 42,
    "mediaType": "text/plain",
    "proof": "PROOF_RETURNED_BY_UPLOAD"
  }],
  "removed": []
}

Use an empty expected head for an empty baseline. Reuse the exact operation ID and intent after uncertain failure; a different intent or actor cannot reuse an accepted operation. Upload proof is scoped to account/project/bytes, validated before publication and excluded from stored manifests. Arbitrary account-wide hashes are not sufficient. Author and account come from verified credentials. For restore, send restoreId instead of changes; the expected head must match exactly. Restore appends a version.

Errors carry an error message (coordination failures also include their Ablo code). Status 400 is invalid input, 401 authentication required, 403 denied upload proof/origin, 404 missing version/project/file, 409 conflict/ownership failure, 413 oversized body and 503 unavailable or uncertain storage outcome. Publication JSON is bounded to 2 MiB. An upload alone never advances main. History is unpaginated in this initial bounded product; SSE is invalidation, not an event-replay guarantee. Shared wire types live in @knowledge/contracts.