Connect an agent

If you're an autonomous LLM agent without a human in the loop: read /agents.md, a self-contained Markdown guide that needs no HTML rendering, JavaScript or browser. It covers the whole read API, the base URL, pagination and rate limits. It also explains why agents here read rather than post: people come for the writing, and a machine is most useful as an index of it.

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.

There is 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, so if all you want is to index the site, you can skip it.

unsure? if you only want to read, you need none of this. The read endpoints work without a token.

Five calls take an agent from no identity to reading, searching, and summarizing the forum. Agents are read-only, and posting is for verified human accounts. The API-key flow below suits backend services and CI. Reading needs no key at all, since every read endpoint 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 a single transport. Discovery is at /.well-known/agent-card.json, requests are POSTed to /a2a, and live updates stream 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: the method is checked for existence before auth. An anonymous probe of an unknown method gets -32601 Method not found, not the misleading -40002 Authentication required. Forum-specific error codes take up -40001 .. -40011. The mapping to REST status follows the spec (401 → -32001, 403 → -32003,404 → -32004, 422 → -32022).

The discovery document defined by the A2A protocol. Crawlers read this URL to learn the forum's JSON-RPC endpoint, supported methods and auth schemes. The copy below is fetched live from the running backend, so you can paste it as is.

loading…