No internet connection
  1. Home
  2. Support

How can I add topics via API?

By @ana
    2021-10-04 15:44:11.809Z

    I'd like to move over some posts from my existing forum via the API. I checked the documentation regarding creating pages and post replies, but couldn't really find what I was looking for.

    Is this the endpoint for adding a new topic? (I wasn't sure if Page = Topic)
    POST https://{hostname}.com/-/v0/upsert-simple

    And, if so, what goes in the body? I tried this and some variations:
    "extId": "aaa",
    "pageType": 10,
    "categoryRef": "extid:bbb",
    "title": "a title",
    "body": "a body"
    That gave me an error saying "403 Forbidden Not allowed. Ask for help at The Talkyard Community [TyEM0UPSSIMPL]". So here I am :D I don't know if it's because the IDs are wrong or something else.
    Btw I have successfully pinged the server with my authorization/basic header, so that shouldn't be the issue. Thank you.

    • 10 replies
    1. The 404 Forbidden was because for those API calls to be allowed, I need to set a per site feature flag. — Now done.

      However, please wait a bit with those API requests?

      I think the endpoint you want to use, is in fact /-/v0/upsert (which should probably get renamed to /-/v0/import). I'll reply here later today or tomorrow, with info about the JSON format.

      /-/v0/upsert-simple was intended for creating new pages, and generating notifications about those new pages. But the pages you're inserting, aren't new. In addition to that, /-/v0/upsert-simple is now a bit deprecated, and instead there's a new Do API at /-/do, via which one can send a bunch of things-to-do, e.g. create new pages and replies, and then Talkyard will do it and generate notifications and (once implemented) webhook events. Whilst /-/upsert won't generate notifications or events; it just silently upserts stuff.

      1. A@ana
          2021-10-05 06:52:16.021Z

          Sure, no rush. Thank you for checking it out, I'll wait to hear more about the JSON format.
          I'm not sure if my pages count as new or not, since they're new here but duplicated from somewhere else. Since I just started my Talkyard community, no one will be receiving notifications either way.
          Definitely interested in knowing more about different endpoints, though.

          1. Sure, no rush

            I'll wait a bit with this, to the end of the week I think. Some other things going on now as well

            I'm not sure if my pages count as new or not, since they're new here but duplicated from somewhere else.

            Hmm maybe "imported" is a better word, than "old". "Imported" pages versus "newly created pages" maybe is clearer than "old" and "new".

            knowing more about different endpoints

            Hmm I can document the /-/v0/upsert endpoint (maybe soon renamed to /-/v0/import (will be backw compat)) and make a list of all API endpoints

            1. A@ana
                2021-10-07 07:30:20.330Z

                If this part of the API isn't ready yet I'll just copy/paste in some posts through the regular interface, no need to make changes on my behalf. I just wasn't sure if I was missing something or not in my original API request.
                And, when you get a chance, a list of endpoints would be awesome.

                1. It actually is ready :- ) However there's no docs, and not enough auto tests. I'm thinking I'll write tests and docs now, shouldn't take long ...

                  1. A@ana
                      2021-10-10 14:46:43.461Z

                      Sounds great, I'll look out for that. Thank you.

            2. In reply toana:
              KajMagnus @KajMagnus2021-10-15 11:17:37.540Z2021-10-15 11:23:42.566Z

              Hi @ana now I've created an automated test that shows, in code, how one can import topics, and shows the JSON format.

              Here's the JSON format:

              Id numbers for things that are getting imported, should start at 2000000001 (or -2000000001 for guests users, which have negative ids — no real accounts).
              And if the extId (external id, e.g. unique Reddit reply id) matches something already in the database, Talkyard updates it. Otherwise, creates it.

              You need to assign an external ID to a category too, where the imported topics get placed. Here's the category, in the JSON: (at the bottom of the file)

              And here's how you can post the JSON to Talkyard — namely via a to-talkyard help script:

              Here's how you'd invoke it: (from the Git repo root)

              nodejs to-talkyard/dist/to-talkyard/src/to-talkyard.js  \
                      --talkyardJsonPatchFile=JSON_FILE  \
                      --sysbotApiSecret=SECRET  \

              But first you'd need to run yarn build in to-talkyard/, so that the to-talkyard/dist/ folder gets generated.


              I'm thinking the above isn't so user friendly. I'll write more nice looking docs during the weekend. (Sorry things "always" take a bit long)

              1. In reply toana:

                Hi again @ana, now I wrote docs about the JSON import file structure: How to Import Discussions to Talkyard

                It's more (longer) docs than what I had thought, and maybe annoyingly many small things to think about. I wonder if in the end it might actually be quicker to copy-paste pages from Reddit instead.

                1. A@ana
                    2021-10-19 13:57:18.571Z

                    Thank you for the documentation! And yeah, I already came to that conclusion myself and have been copying/pasting over important pages :) . Still, I'll check out the documentation and see if I can automate part of this.

                    1. Ok :- )   (If in the end you decide to create some script, it'd be interesting to hear)