Sponge reference

This section is generated from the OpenAPI 3.1 document (Sponge API 1.0.0) and lists every agent-facing operation. Operator-only operations are omitted. Private calls send a short-lived bearer token from the Agent access page as Authorization: Bearer; a request that also carries a cookie is refused so browser sessions and delegated tokens never mix.

Headers and conventions

• Canonical reads return a bare Sponge-Revision; semantic writes send it back as Sponge-If-Revision. A missing revision answers 428, a stale one 412.
• Every write needs an Idempotency-Key. An exact retry reuses its key, body, and revision; a new intent needs a new key.
• meta.requestId and X-Request-Id are always server-minted; a client-supplied X-Request-Id is echoed as meta.clientRequestId.
• Authenticated responses carry X-Sponge-Requests-Remaining and, when known, X-Sponge-Research-Runs-Remaining.
• A weak ETag validates GET caches only; canonical GETs honor If-None-Match with 304. It is never a command precondition.
• A Markdown read carries its loss count in X-Sponge-Markdown-Loss-Count.
• A known path called with a method it does not implement answers a JSON 405 with an Allow header. Unknown /api/v1 paths answer JSON NOT_FOUND.
• Errors are JSON objects with error.code, error.message, optional error.requiredAction, and meta.requestId; the codes are listed under Errors.

Operations

The graph stores 18 immutable record kinds. They are semantic and authority records, not a fixed inventory of things in the universe. Source, person, organization, account, place, event, work, artifact, concept, process, and future domains are reviewed vocabulary terms, not privileged root records.

Activity

An attributable action such as import, proposal, review, transformation, or publication.

Assertion

An attributable stance toward one Statement for a declared purpose and Context.

Context

A precise boundary for time, place, language, perspective, version, or scenario.

Dependency manifest

The complete ordered set of exact records required to reproduce an edition.

Edition

An immutable synthesis whose passages retain exact support and policy dependencies.

Entity

A durable identity anchor independent of its labels, types, and external identifiers.

Evidence

A typed account of how a source, observation, selector, or method bears on an Assertion.

Identity operation

A reviewed merge, split, redirect, quarantine, rekey, or tombstone over identity anchors.

Inquiry

A human question and the bounded investigation it initiates.

Inquiry event

One append-only step in an Inquiry, including a gap, observation, proposal, or decision.

Review decision

A human decision over an exact proposed effect under one review purpose.

Rights decision

A purpose-bound decision describing where an exact subject may be disclosed.

Schema

An immutable definition for a concept, predicate, unit, mapping, or extension value.

Shape

A composable validation and projection lens for one use, domain, or audience.

Statement

An immutable proposition with a subject, predicate, typed object, and qualifiers.

Type membership

Evidence-bearing membership of an Entity in a versioned concept.

View

A purpose-bound specification for selecting and presenting exact graph state.

Vocabulary

A versioned, owned collection of concepts, predicates, units, mappings, and Shapes.

Entity: "Voyager 1"
Type membership: Spacecraft
Statement: "Voyager 1 entered interstellar space"
Context: { time: "2012", definition: "plasma-density boundary" }
Assertion: { stance: "supports", purpose: "research" }
Evidence: { source: "mission report", selector: "findings" }
Projection: { purpose: "public encyclopedia", edition: "immutable" }

An Entity or Inquiry ID is an opaque identity anchor. Labels, classifications, external URLs, and vocabulary revisions can change without changing that anchor. A graph revision identifies exact knowledge state; an Edition digest identifies exact synthesis bytes; a release determines whether a public locator resolves.

Edition

https://sponge.computer/k/edition/<edition-id>/<edition-digest>

Entity

https://sponge.computer/k/entity/<entity-id>/<graph-revision>

Inquiry

https://sponge.computer/k/inquiry/<inquiry-id>/<graph-revision>

Every public page is also available as Markdown by adding .md to its address or requesting it with Accept: text/markdown. Exact released JSON is at /api/v1/public/artifacts/{kind}/{artifactId}/{revision}.

How identity stays conservative

• Similar names, shared URLs, model confidence, or overlapping types never merge two anchors automatically.
• Identity operations require explicit review and preserve enough history to understand or recover the change.
• A locator is not an access grant. It resolves only through a current, purpose-bound public release.

Document

A private, versioned rich research workspace composed of stable nested blocks.

Block

A durable, document-scoped unit of rich content. Moving or nesting a block does not change its identity.

Space

The private knowledge boundary that holds a document's Inquiries, graph records, proposals, and reviews. The evidence picker searches the current document's space; nothing private crosses from one space to another.

Lease

A short-lived, exclusive right to change one block or to decide one review item. The server checks the lease before it applies an edit or a decision. A selected block is not a lease, and an expired lease is refused rather than forced.

Grant

A named person's bounded access to one document or block. Sign-in and a live grant are both required; a link alone never grants access.

Source

An Entity classified as a citable information resource through reviewed vocabulary and evidence.

Citation

A document reference to exact graph evidence, with its bearing, selector, Context, and graph revision.

Excerpt

A short passage copied exactly from a source, with the date it was retrieved, that a reader can inspect beside the claim it supports.

Claim

A reviewed statement about the world that a document or edition passage rests on. A claim whose sources carry no usable excerpt is reported as a gap instead of a finding.

Inquiry

A human question with a private, append-only trail of research events, gaps, proposals, and decisions.

Entity

A durable identity anchor for something that can be referred to, independent of its labels, types, and external identifiers.

Document proposal

An agent's proposed change to the text or structure of a document. It changes nothing until a person applies it, and it never touches the knowledge graph.

Knowledge proposal

An agent's exact, bounded change set for the knowledge graph. It has no authority until a person reviews it.

Promotion review

The second, separate review of an accepted research effect for the public-encyclopedia purpose. Acceptance for research use never implies promotion.

Shape

A versioned, composable validation and projection lens for one purpose or domain.

Graph revision

The identifier of one exact state of a space's knowledge graph. Citations, released entity and Inquiry pages, and edition dependency manifests pin a graph revision so later changes cannot rewrite what they meant.

Edition

An immutable synthesis whose passages and complete dependencies have passed human review.

Publication enablement

The explicit decision by a space owner that editions from that space may be released. Without it, no edition from the space can receive a public locator, whatever has been accepted.

Release

The explicit public binding between an eligible edition, entity, or Inquiry and its canonical /k locator.

Public page

A server-rendered page anyone can read without a session: a released edition, entity, or Inquiry under /k, or a published document or block.

Research note

A dated essay on sponge.computer that explains one product mechanism with primary sources; not a knowledge page and never generated by a model.

Artifact

The docs' superset term for a released edition, entity, or Inquiry, the three kinds a /k locator can name.

Every error is a JSON object with a stable error.code. Statuses mirror the route handlers; JOB_FAILEDarrives inside a research job's terminal state rather than as an HTTP status.

API values derive from the published contract, so they match OpenAPI. Per-token request budgets are chosen on the Agent access page and reported by GET /api/v1/auth.

Docs edition 2026.09, reviewed 2 September 2026. The docs are split into Start, Guides, Concepts, Reference, and Status pages as of this edition; older section links still resolve to their new home. API changes below come from the OpenAPI document, newest first.

2026-09-02

Every path answers unimplemented methods with a JSON METHOD_NOT_ALLOWED (405) and an Allow header. Every operation enumerates the statuses its handler can emit; the working-memory operations carry the ops tag and everything else the agent tag; every component has one example; x-sponge-credential-boundary has one object shape; the event stream framing and caps are published under x-sponge-event-stream; Last-Event-ID is a string header.

2026-09-02

New credential scope research:read reads a job, its events, its list, and its Markdown report without research:run; every operation that accepts either scope lists both under x-sponge-required-scopes-any-of. GET /api/v1/research-jobs/{jobId}/report?format=rich-json now also requires document:read. A document or job outside the credential's boundary answers 404 on every route instead of 403.

2026-09-02

GET /api/v1/documents/{documentRef} accepts format=blocks (a flat block list with stable IDs, parents, indexes, and per-block Markdown) and format=markdown (a whole-document projection with X-Sponge-Markdown-Loss-Count). DocumentMutationRequest fence fields oldParentBlockId, oldSiblingBlockIds, newSiblingBlockIds, parentBlockIds, and siblingBlockIds are optional; the server derives parents from the exact snapshot and checks any supplied value. Every schema field is described and nested definitions are hoisted to components.schemas.

2026-09-02

GET /api/v1/auth returns documentRef and browserHref for a document-bound credential. GET /api/v1/documents and GET /api/v1/research-jobs list summaries with opaque cursors.

2026-09-02

meta.requestId and X-Request-Id are always server-minted; a client-supplied X-Request-Id is echoed as meta.clientRequestId. Authenticated responses carry X-Sponge-Requests-Remaining and, when known, X-Sponge-Research-Runs-Remaining. Canonical GETs honor If-None-Match with 304. The report endpoint returns retryable REPORT_NOT_READY with Retry-After instead of CONFLICT. Activation-blocked operations no longer charge the request budget. The principal carries an optional budgets object.