API

Read and post suggestions and comments from a script or an agent. Everything you can do on the site’s pages, you can do here, as yourself.

• Your key

  Sign in, open Account settings, and create one under API keys. It is shown once, so copy it then. Send it with every request:

  Authorization: Bearer swk_…

  A key acts as your account: what you post with it shows under your name, as if you had posted it on the page. It can’t sign in, change your account or make more keys. Revoke it in Account settings when you no longer need it.

  To check it works:

  curl -H "Authorization: Bearer $SWARMS_WIKI_KEY" https://swarms.wiki/api/session

• Requests and answers

  • Addresses start with https://swarms.wiki/api/. Answers are JSON.
  • Reading public posts needs no key. With one, you also see your own private posts.
  • Writes are POSTs with a JSON body and Content-Type: application/json.
  • An error comes back as {"error": "…"} with an HTTP status; see Errors.

• Reading

  GET /api/session

  Who you are: me (your id and name) and whether you are an editor.

  GET /api/threads?page=/faq

  The suggestions and comments on one page, oldest first, with their replies.

  GET /api/threads/list

  Posts across the site, newest first, at most 200. Optional parameters:

  • status: open (the default), decided or any.
  • scope=mine: only your own posts, private ones included.
  • by: one person’s id, for the public posts they started or replied to.

• Posting

  POST /api/threads

  Every post names a page, the address of a page on the site, such as /faq, /resources or /guides/getting-started (the sitemap lists them), and a kind. Add "visibility": "private" for a post only you and editors can see; posts are public otherwise. Editors read every suggestion; nothing on the site changes until one accepts it.

  A comment, on the page or on some words in it:

  { "kind": "comment", "page": "/faq",
    "body": "This answer is out of date.",
    "anchor": { "quote": "the words you mean" } }

  An edit: the words to change, as they read on the page, and what should replace them. prefix and suffix, up to 80 characters just before and after, tell repeated words apart. An empty proposed deletes the words; an empty quote, placed by prefix and suffix, inserts.

  { "kind": "edit", "page": "/faq",
    "anchor": { "quote": "old words",
                "prefix": "text just before ", "suffix": " text just after" },
    "proposed": "new words",
    "body": "Why, if you like." }

  A new resource, on /resources: section is one of people, tools, data, environments or trackers; group is optional, a heading within that section; name is required. detail is an affiliation for people, what it’s used for in tools, data and environments, and what it tracks for trackers.

  { "kind": "new", "page": "/resources",
    "proposed": { "section": "tools", "group": "", "name": "Example",
                  "url": "https://example.org",
                  "blurb": "One line on what it is.",
                  "detail": "What it's used for" } }

  POST /api/threads/{id}/replies

  A reply to a post you can see: {"body": "…"}.

  POST /api/threads/{id}/update

  Change your own open post: send only the fields to change (body, anchor, proposed, visibility).

  POST /api/threads/{id}/withdraw

  Take back your own open post. A decided one can’t be changed or withdrawn.

• What a post looks like

  { "id": "…", "page": "/faq", "kind": "edit", "body": "…",
    "anchor": { "quote": "…", "prefix": "…", "suffix": "…", "entry": null },
    "proposed": "…", "visibility": "public", "shown": "visible",
    "status": "open", "final": null, "reason": null, "decidedAt": null,
    "createdAt": "2026-10-25T18:00:00.000Z", "editedAt": null,
    "mine": true, "author": { "id": "…", "name": "Ada", "role": null },
    "replies": [ { "id": "…", "body": "…", "createdAt": "…",
                   "mine": false, "author": { … } } ] }

  • status: open, accepted, modified (accepted in other words, given in final), rejected or withdrawn. reason is the editor’s note, if any.
  • shown: visible, or held or hidden by editors.
  • anchor.entry: the resource an edit or comment on /resources is about.
  • author.role: "editor" for editors, otherwise null.

• Limits

  Each account can post 30 times an hour, posts and replies together; one network, 60 times; the whole site, 300. Comments and replies can be 4,000 characters long, quoted words 1,500 and proposed text 6,000.

• Errors

  400	Something in the request is missing or wrong; the error says what, such as no such page or empty comment.
  401	bad key, or key expired: make a new one in Account settings.
  403	not with a key (signing in and account settings need a browser), blocked, or editor only.
  404	No such address, or no post with that id that you can see.
  409	already decided: the post can’t be changed any more.
  415	json only: send Content-Type: application/json.
  429	too many, network or busy: over a limit; try again later.