Start with Sponge

In about ten minutes you will have a private document with one paragraph, one citation (a reference to an exact piece of evidence in your space), and a Markdown export of both. Anyone with a Hraness account can sign in.

1. Sign in.Open sponge.computer and choose Start a private question. Sign in with your Hraness account when asked.
2. Create a document.Open New document. The document is private to you from the first keystroke; getting a URL does not publish it.
3. Write the question.Type the question you want answered as the first paragraph, then write one sentence you believe is true about it. Saved state follows server acknowledgement, so the save indicator tells you when the server holds your text.
4. Open the evidence picker.Place the cursor at the end of your sentence and open the citation evidence picker from the editor toolbar. The picker searches the reviewed sources in your document's space and shows human-readable details, never private graph identifiers.
5. Choose a source and state its bearing.Pick the source that supports your sentence and mark whether it supports, contradicts, corroborates, quotes, reports a method, or provides background. A bracketed number appears in your prose.
6. Check the Sources list.The document's Sources list now shows the source with its title, publication year, and evidence kind, numbered in reading order.
7. Export Markdown.Open the document menu and choose Export…. Portable Markdown carries the text and a loss report naming what it could not encode; the lossless recovery copy carries the citation exactly.

If your space has no reviewed sources yet, start a research job from the document's chat instead: it gathers sources, cites them with excerpts, and ends with a Sources block the application writes. What each evidence kind can support is explained in Evidence kinds and citability.

The v1 agent API gives your own coding agent a small JSON API for private document work and durable research. Bring your own inference: your agent reasons, Sponge stores exact state. In four commands you will create a token, confirm it, create one private document, and read the revision you need for every later write.

Sign in and open the Agent access page to create a token. Account-wide access is needed only to create the first document; a document-bound token covers later work. Choose only the capabilities, request budgets, and expiry the task needs. Then run these four commands.

1. Create an account-wide token on the Agent access page, then export it. Tokens are short-lived.

   export SPONGE_API_TOKEN="paste-the-token-here"

2. Confirm the token and its remaining request budget.

   curl -s https://sponge.computer/api/v1/auth \
     -H "Authorization: Bearer $SPONGE_API_TOKEN"

3. Create one private document. The response body carries its opaque documentRef.

   curl -s https://sponge.computer/api/v1/documents \
     -H "Authorization: Bearer $SPONGE_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: first-doc-$(date +%s)" \
     -d '{"v":1,"title":"How should this question be investigated?"}'

4. Read the document and keep the Sponge-Revision header; every later write sends it back as Sponge-If-Revision.

   curl -si https://sponge.computer/api/v1/documents/sdoc_YOUR_DOCUMENT_REF \
     -H "Authorization: Bearer $SPONGE_API_TOKEN" | grep -i '^sponge-revision\|^{'

Creating a document does not start a research job or publish anything. From here, an agent works in one loop.

1. Read exact state.Keep the bare Sponge-Revision, document version, and content digest returned with the canonical rich document. The same read offers format=blocks, a flat list of blocks with their stable identifiers, parents, positions, and per-block Markdown, and format=markdown, a whole-document Markdown export with a counted loss report. A weak ETag validates GET caches only and is never a command precondition. Opaque references remain opaque.
2. Apply semantic changes.Send a bounded mutation with a fresh idempotency key (a client-chosen string that makes a retry safe) and the exact revision in Sponge-If-Revision. An exact retry reuses its original key, body, and revision even if the document has advanced. A missing revision returns 428; a stale changed command returns 412, so refresh the document and replan.
3. Delegate when useful.Start one durable research job in the same document, then poll canonical state or resume its monotonic event stream. Sponge uses one server-owned inference configuration. Research requests describe the report, not its execution policy. Report export returns exact rich JSON or loss-reported Markdown only after the report is ready.
4. Hand judgment back.An agent may propose work, but only a person can decide a review, expand rights, resolve identity, finalize an edition, enable publication, or publish.

GET  /api/v1/auth
GET  /api/v1/documents
POST /api/v1/documents
GET  /api/v1/documents/{documentRef}?format=rich-json|blocks|markdown
POST /api/v1/documents/{documentRef}/mutations  Sponge-If-Revision: <revision>
GET  /api/v1/research-jobs
POST /api/v1/research-jobs
GET  /api/v1/research-jobs/{jobId}/events
GET  /api/v1/research-jobs/{jobId}/report?format=markdown

An agent that loses its place can find it again without asking a person. GET /api/v1/auth tells a document-bound token the exact documentRef and browser path of its one document. GET /api/v1/documents and GET /api/v1/research-jobs return bounded pages of summaries, newest first, with an opaque cursor for the next page. A document list shows only documents the token can reach, and a job list shows only jobs that token started. A token with the read-only research:readcapability can observe jobs and read their Markdown reports without starting, cancelling, or exporting the full document. Anything outside a token's boundary answers 404, the same as a missing reference, so a not-found answer never confirms existence.

A direct API client can add an optional acceptanceobject to a v1 report specification. It binds up to 16 coverage requirements to specified term groups, one as-of date, a zero-to-one confidence value, same-block ratio and percentage checks, and visible body-word limits. The body-word count includes rendered citation labels; term, date, confidence, and ratio checks use the report's authored prose. Sponge may repair a draft within the bounded research run, but the final rich report is not ready for export until it satisfies the contract. Omit acceptance to use the standard profile readiness rules. OpenAPI defines the exact fields and limits.

Sponge's own command-line client uses the same contract: sponge document create, document show, and document apply for the exact snapshot loop, plus sponge research commands for durable delegation, observation, report export, and explicit cancellation. It is not published as a package; external agents call the HTTP contract directly, and the downloadable skill does not depend on it. The API, discovery manifest, and skill are live at sponge.computer.

Every operation, scope, header, and status is in the API reference; every error code and what to do about it is under Errors. The Sponge developer resources page collects the same discovery links, and llms.txt names when to use Sponge.