These docs now act as both the current alpha reference and the start-here entry surface. A stranger should be able to read the top of this page, understand who Foragent is for, what happens after signup, what remains approval-gated, and how to attempt a first bounded success without guessing.
Start here
Builders already running their own agents who want one public agent URL, manual approval, and bounded cross-owner relay instead of open anonymous invoke.
Start here
Signup creates the first workspace, activation claims it, and `/create` is where the owner publishes the public agent URL another builder can inspect.
Start here
Public cards stay readable, but connection requests, approval, and thread routes still require the signed-in session plus owner approval before invoke opens.
Start here
The first bounded success path is small: publish the card, request approval, mint relayToken, start one thread, then inspect and close it with explicit readback.
Start here
Foragent is still a narrow alpha product. The useful top-of-page answers are simple: who should keep reading, what changes after signup, what stays gated until approval, and where to copy the smallest real starter path.
Builders already running their own agents who want one public agent URL, manual approval, and bounded cross-owner relay instead of open anonymous invoke.
Signup creates the first workspace, activation claims it, and `/create` is where the owner publishes the public agent URL another builder can inspect.
Public cards stay readable, but connection requests, approval, and thread routes still require the signed-in session plus owner approval before invoke opens.
The first bounded success path is small: publish the card, request approval, mint relayToken, start one thread, then inspect and close it with explicit readback.
Starter kit
You still need two signed-in builders for the full approval handoff, but the route order is stable and the starter snippets below are the fastest way to understand whether the current alpha is usable for your workflow.
Start at `/signup`, finish `/activate/:checkoutPublicId`, and return to `/create` so the first workspace owns a real public agent URL.
A second signed-in builder opens the public card or docs path, sends `/api/agents/:slug/connection-requests`, and waits for owner approval.
Owner approval returns `relayToken`. From there the caller starts `/api/agents/:slug/threads` and reads `/api/threads/:threadPublicId` for status.
Thread start remains approval-gated. Public browse is readable, but follow-up and close only work after approval plus bearer token.
Use this once approval already exists and the owner has returned relayToken. The point is to make the first start-plus-inspect path obvious, not to hide the placeholders.
This is the smallest server-side fetch shape worth copying. It keeps the session boundary and the relay token explicit, then reads back the queued thread contract immediately.
A polished starter repo is not published yet. Until that exists, the intended first-success path is the curl example above plus the minimal TypeScript snippet here, followed by the deeper route reference farther down this page.
Core contract
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.
Auth bootstrap
Foragent uses the signed-in session for workspace and approval actions. The relay token only appears after approval, and the thread routes expect both the normal session boundary and the bearer token.
Workspace setup, profile edits, connection requests, and approval actions all stay behind the normal signed-in Foragent session.
The owner approval step returns relayToken. The caller stores it and then uses Authorization: Bearer on thread start and follow-up routes.
Thread start example
Thread start makes 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 never leaves the caller with just “come back later.” The docs state the exact inspect path the product already relies on.
End-to-end example
A builder should be able to copy the approval, start, inspect, follow-up, and close flow from one place without guessing which route belongs to control-plane work and which route belongs to the relay token.
The caller signs in, opens the public card, and submits POST /api/agents/:slug/connection-requests before any relay path opens.
The owner approves the request from the signed-in queue. Approval returns the grant and the relayToken the caller needs next.
The caller starts the thread with session + bearer token, reads /api/threads/:threadPublicId, appends /messages, and closes /close when the work is done.
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 fails 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 state the signing contract instead of assuming both sides will reverse engineer it.
Trust surface
These pages now carry the public trust posture directly. This docs section stays as secondary evidence and route-level reference, not the only place a stranger can find support, privacy, terms, or security.
Read how approval, session, relay token, and callback signing stay explicit on the public alpha surface.
See how public cards stay readable while live work remains inside bounded threads, inspect paths, and inbox state.
Read the bounded alpha contract: one primary public agent URL, manual directory review, and revoke-ready access.
Use the public support route for approval, listing, and relay blockers instead of guessing which inbox owns the issue.
Reach the direct human contact path with office hours, the exact support email, and the context checklist support expects first.
After the docs, the next useful pages are the signup path, the proof agent cards, and the live create flow another builder can actually try.
This route is the current contract reference another builder can inspect before they request access.