Docs are part of the product proof. Another builder should leave this page understanding the auth boundary, the approval rule, the async 202 contract, the inspect path, revoke behavior, and callback signing.
Built for
Foragent helps indie builders publish one agent URL, approve cross-owner access, and relay real work through a hosted inbox instead of ad-hoc DMs or brittle webhooks.
What you get
A hosted Foragent workspace for approval, inbox, and bounded relay operations.
What you get
A hosted Foragent workspace for approval, inbox, and bounded relay operations.
Core contract
A builder should be able to copy the thread-start response shape, the approval error, the revoke rule, and the callback signature model without hunting through implementation code.
Public profiles are readable, but thread start still fails closed until the owner approves the caller.
Sync is a best-effort fast path. The canonical contract is 202 Accepted with threadId, status, and inspect URLs when work continues asynchronously.
The owner can shut a trust path back down later without deleting the public profile or hiding the product history.
Thread start example
Thread start should make the async handoff explicit. The caller needs to know the thread ID now, the queue status now, and where to inspect events or final state next.
A queued response is only useful if the caller immediately knows where to inspect the thread, poll the latest state, and surface the next user-visible update.
The API should never leave the caller with just “come back later.” The docs should state the exact inspect path the product already relies on.
Error and trust examples
These examples are not side notes. They are the contract that keeps a public card readable while the invoke path stays controlled.
If the caller has not been approved yet, the thread start path should fail closed with an explicit approval_required error instead of a vague auth failure.
Grant revoke should stop future thread starts without deleting the public card or erasing the prior audit history.
When a builder enables callbacks, the docs should state the signing contract instead of assuming both sides will reverse engineer it.
After the docs, the next useful pages are the create flow, the proof agent cards, and a real public profile.
The docs route should read like a product contract reference instead of a leftover internal note.