Connect an agent

If you're an autonomous LLM agent without a human in the loop: read /agents.md, a self-contained Markdown bootstrap. No HTML rendering, no JavaScript, no browser. It covers the read surface end to end, the base URL, pagination, rate limits and why agents read here rather than post: the writing is what people come for, and an index of it is what a machine is for.

The path below is for a human-supervised integration: a developer wiring an API key into a service. If that's you, keep reading. If you're the agent itself, follow /agents.md and skip the cards.

One way to put an agent on the forum: a principal bound to an API key, exchanged for a scope-graded JWT. Reading needs neither, and that is the shorter road if all you want is to index us.

unsure? if you only want to read, you need none of this: the read surface answers without a token.

Five calls take an agent from no identity to reading, searching, and summarizing the forum. Agents are read-only; posting is for verified human accounts. The API-key flow below is the right path for backend services and CI, and reading needs no key at all: the whole read surface answers an anonymous caller.

curl -sX POST https://commongnd.org/api-origin/auth/register \
  -H 'content-type: application/json' \
  -d '{"identityType":"api_key","displayName":"my-agent"}'

curl -sX POST https://commongnd.org/api-origin/oauth/token \
  -H 'content-type: application/json' \
  -d '{"grant_type":"api_key_exchange","api_key":"YOUR_API_KEY"}'

curl -s 'https://commongnd.org/api-origin/v1/threads?limit=20&contentType=question'

curl -s "https://commongnd.org/api-origin/v1/threads/<thread-uuid>" -H "authorization: bearer $TOKEN"
curl -s "https://commongnd.org/api-origin/v1/threads/<thread-uuid>/replies?limit=50" -H "authorization: bearer $TOKEN"

curl -s "https://commongnd.org/api-origin/v1/search?q=last-event-id+reconnect&type=thread&limit=10" \
  -H "authorization: bearer $TOKEN"

Every REST verb has a JSON-RPC equivalent for agents that prefer one transport. Discovery via /.well-known/agent-card.json, requests POST'd to /a2a, live updates streamed from /a2a/stream over SSE. Auth is the same Bearer JWT you use for REST.

# request: POST https://commongnd.org/api-origin/a2a
{
  "jsonrpc": "2.0",
  "id": "01",
  "method": "list-threads",
  "params": { "limit": 20, "contentType": "question" }
}

# response
{
  "jsonrpc": "2.0",
  "id": "01",
  "result": { "data": [ ... ], "pagination": { "nextCursor": "..." } }
}

# stream: GET https://commongnd.org/api-origin/a2a/stream  (Accept: text/event-stream)
event: thread.created
data: {"id":"...","title":"SSE stream drops on reconnect..."}

event: comment.created
data: {"id":"...","threadId":"...","authorPrincipal":"..."}

→ Dispatch order: method-existence is checked BEFORE auth. An anonymous probe of an unknown method gets -32601 Method not found, not the misleading -40002 Authentication required. Forum-specific error codes occupy -40001 .. -40011; mapping to REST status mirrors the spec (401 → -32001, 403 → -32003,404 → -32004, 422 → -32022).

Discovery document per the A2A protocol. Crawlers read this URL to learn the forum's JSON-RPC endpoint, supported methods, and auth schemes. Live fetched from the running backend below. Copy and paste, no parsing surprises.

loading…