How to create Pages and Comments via the API

You can create pages (a.k.a. topics, posts, threads) and comments via Talkyard's Do API.

First, read about the Talkyard API authentication, including about how to enable the API. And the API shorthand syntax. Then:

Creating pages

1. Generate an API secret (at https:// your forum /-/admin/api).
2. Open the forum category where you want your pages to appear (you'll find all categories here: https:// your forum /categories). Click Edit category. Scroll to the bottom of the dialog that then opens, click External ID and type an ID of your choosing. (This field will be renamed to "Reference ID", because you use these IDs to reference things.)
3. Decide who (which user) should be the page author. You can use Sysbot (username sysbot) if it's not a person.
4. Send a POST request to /-/v0/do:

POST https://your-talkyard-site/-/v0/do  {
  doActions: [{
    asWho:  'USER_REF',
    doWhat: 'CreatePage',
    doHow: {
      refId?: 'NEW_PAGE_REF_ID',
      pageType: 'Discussion' | 'Idea' | 'Question' | 'Problem',
      inCategory: 'CAT_REF',
      title: "Page Title",
      body: "Text _italic_ **bold** ...",
      bodyFormat?: 'CommonMark',
    }
  }]
}

• The USER_REF says who's the author. You can specify a username, like so: "asWho": "username:some_username".
• If you're going to interact with the new page via the API (e.g. posting comments, more about that below), then, give it a reference ID — NEW_PAGE_REF_ID above.
• The CAT_REF is from step 3 above, format rid:CAT_REF_ID where CAT_REF_ID is whatever you typed in the Externa ID field. (The "rid:" prefix means "Reference ID".)

Here follows an example, using cURL.   Fill in SERVER_ORIGIN, SECRET_B64, USERNAME, YOUR_PAGE_REF_ID and CAT_REF_ID. And, the page title and body text, if you can think of anything better. (Must be in CommonMark.)

curl -X POST  SERVER_ORIGIN/-/v0/do  \
    -H 'Authorization: Basic SECRET_B64'  \
    -H 'Content-Type: application/json'  \
    -d '{ "doActions": [{
      "asWho": "username:USERNAME",
      "doWhat": "CreatePage",
      "doHow": {
          "refId": "YOUR_PAGE_REF_ID",
          "pageType": "Discussion",
          "inCategory": "rid:CAT_REF_ID",
          "title": "Bird vs Owl",
          "bodySrc": "The _early_ bird catches the worm, but the wise owl shops online at midnight",
          "bodyFmt": "CommonMark"
      }
    }]}'

Response:

{"results":[{"ok":true,"res":{"pageId":"3","pagePath":"/-3/bird-vs-owl"}}]}

Note that there's an array — in case you do many things in the same API request.

Creating comments

This is simialr to creating pages, except that you change doWhat to CreateComment, and specify a page and a parent post, instead of a parent category.

POST https://your-talkyard-site/-/v0/do  {
  doActions: [{
    asWho: 'username:___',
    doWhat: 'CreateComment',
    doHow: {
      refId?: 'NEW_REF_ID',
      parentNr: 1,  // the Orig Post is nr 1
      whatPage: 'rid:YOUR_PAGE_REF_ID',
      bodySrc: 'Comment text _italic_ **bold**',
      bodyFmt: 'CommonMark',
    }
  }]
}

Types and sample code

Here're Typescript declarations for the API:
https://github.com/debiki/talkyard/blob/8ee633dd11d65b08610eca034324aafffcc59928/tests/e2e-wdio7/pub-api.ts#L1246

if you scroll down a bit from there, you'll find types CreatePageParams and CreateCommentParams.

Here's an end-to-end test that creates pages and comments: (and tag types and tags, but you can ignore that)
https://github.com/debiki/talkyard/blob/8ee633dd11d65b08610eca034324aafffcc59928/tests/e2e-wdio7/specs/do-api-create-pages-comts-check-webhooks-search.2br.e2e.ts#L182

If you manage to actually run the e2e test (you might waste a week!), it'll print cURL commands for each API request.