Build with Sponge

Sponge developer resources

Connect your coding agent to private documents and their retained evidence. Start with the four commands below, or give your agent the downloadable research skill. The versioned HTTP API and OpenAPI 3.1 contract describe the same supported operations.

When to call Sponge

Use your own agent to investigate, read retained passages, and create or revise a private document. Public Entity, Inquiry, and Edition pages can be read without a token. A person must review research, confirm rights, and choose what to publish.

Make your first API call

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. Then run these four commands.

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"
```

Confirm the token and its remaining request budget.

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

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?"}'

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 hosted research or publish anything. Hosted research is retired. The Sponge research skill continues with retained evidence, research in your current agent, recoverable mutations, and document export. Historical reports and job state remain available for reading, review, or cancellation.

Discovery

HTTP contract

Private calls use a short-lived bearer token created by a signed-in person on the Agent access page. Every operation publishes its exact scope, document-boundary rule, and byte limits in OpenAPI. Canonical reads return a bare Sponge-Revision header. Semantic writes require Sponge-If-Revision and a fresh idempotency key. Errors are JSON objects with error.code, error.message, optional error.requiredAction, and meta.requestId.

Anonymous public reads are limited to exact released public pages at /api/v1/public/artifacts/{kind}/{artifactId}/{revision}. Unknown /api/v1 paths return JSON NOT_FOUND.

Error codes and recovery

Code	HTTP status	Meaning	What to do
`INVALID_REQUEST`	400	The request did not match the published schema or size limits.	Compare the body, headers, and query with OpenAPI, then send a corrected request.
`AUTH_REQUIRED`	401	No valid Sponge agent credential arrived.	Create a token on the Agent access page and send it as Authorization: Bearer.
`AUTH_AMBIGUOUS`	401	A bearer token and a browser session were presented together.	Send one bearer token without a Suite session cookie.
`FORBIDDEN`	403	The credential lacks the scope or the document boundary for this operation.	Use a token with the required scope, or one bound to this document.
`NOT_FOUND`	404	No resource is visible to this credential at that locator.	Check the reference or path against OpenAPI; unknown /api/v1 paths return this code too.
`IDEMPOTENCY_REQUIRED`	400	A write arrived without an idempotency key.	Add an Idempotency-Key header of 16 to 128 safe characters and resend.
`IDEMPOTENCY_CONFLICT`	409	The idempotency key is already bound to a different request.	Choose a new key for the new intent, or repeat the original body exactly.
`PRECONDITION_REQUIRED`	428	A semantic write arrived without a revision precondition.	Read the document, then send its revision in Sponge-If-Revision.
`PRECONDITION_FAILED`	412	The revision in Sponge-If-Revision is stale.	Read the current document, replan against it, and resend with the new revision.
`CONFLICT`	409	The current state does not allow this command.	Read the current document or job state before repeating the command.
`RATE_LIMITED`	429	The credential's request budget is exhausted for now.	Wait for the Retry-After interval, then continue.
`TEMPORARILY_UNAVAILABLE`	503	A dependency was unavailable or the surface is not activated.	Honor Retry-After when present. Public API search remains unavailable; private reads may be retried after a temporary dependency failure.
`REPORT_NOT_READY`	409	The research job has not staged its report yet; this is a polling state, not a conflict.	Wait for the Retry-After interval, then read the canonical job until artifacts.report is present.
`METHOD_NOT_ALLOWED`	405	The path exists but does not implement this HTTP method.	Use one of the methods named in the Allow header for that path.
`FEATURE_RETIRED`	410	Fresh hosted research, source analysis, or monitoring has been retired.	Use your own agent with retained sources and document tools. Recover only exact previously accepted requests; do not retry fresh hosted starts.
`AGENT_RUN_REQUIRED`	409	A historical agent-only operation required a hosted run.	Use the external proposal endpoint with a document-bound token; hosted job creation is retired.
`JOB_FAILED`	job state	A research job ended without a report, reported inside the job state.	Read the terminal error and retain its history. Continue new research with your own agent.
`INTERNAL_ERROR`	500	An unexpected failure that the contract reserves a code for.	Retry once with the same idempotency key, then report meta.requestId.