No internet connection
  1. Home
  2. Support

Is there any API documentation?

By Tim Martin @timmartin
    2020-04-21 10:32:32.589Z

    I have successfully created an API key, but I can't find any documentation of the API, even a list of what endpoints are available. Where should I be looking?

    Solved in post #2, click to view
    • 11 replies

    There are 11 replies. Estimated reading time: 11 minutes

    1. Hi Tim, I started writing docs here: https://www.talkyard.io/forum/latest/docs — right now there's just one article, about Single Sign-On via API.

      There's an create-new-topics and create-new-replies API too, and soon a search API.

      What could you be interested in doing, via an API?

      ReplySolution
      1. TTim Martin @timmartin
          2020-04-22 07:28:44.746Z

          Thanks for the information. At the moment I'm still figuring out my design, so I don't have a fixed idea what I need to do, I was hoping to figure out what was possible. My main interest is in providing more integration between the Q&A forum and other pages of my site. So perhaps being able to embed the top 5 most popular questions on topic X within a page relating to that topic (i.e. I'd need an API that can return topics by tag, sorted by popularity or similar). I might also use the API for creating new topics, but it sounds like that's already available.

          To be honest, I'm looking to get an MVP together quite quickly here so I'm not sure that this solution is going to work for me. It's possible we'll come back to it in the longer term.

          1. KajMagnus @KajMagnus2020-04-25 07:21:01.564Z2020-04-25 07:28:01.231Z

            I like the "embed the top 5 most popular questions on topic X within a page relating to that topic" idea.

            I started a list of API ideas here: https://www.talkyard.io/-379/talkyard-api-ideas

            (I'm curious what the MVP will be about? Sorry if maybe I cannot implement features and API endpoints fast enough for your situation — but thanks anyway for the ideas & feedback you posted :- ))

            Maybe this Top 5 Topics in Category / Tag X could be the Search API, but with the full text query left out. Something like: POST /-/v0/search with JSON:

            { searchQuery: {  tagRefs: [tagX],  orderBy: SortOrder.PopularFirst,  limit: 5 }}
            
            1. @timmartin — I'm almost done adding an "list the X most popular questions on topic X" API. I realize you probably won't use it, because you were short of time — still, it's a good idea. And I think it was good to see how this Find-popular-topics-about-X API, can share code with the upcoming full text search API.

              Seems the find-popular-topics-about-X API will look like:

              POST /-/v0/list  {
                listQuery: { findWhat: 'Pages', lookWhere: { inCategories: [categoryX] },
                orderBy: 'PopularFirst',
                limit: 5,
              }
              

              Whilst, full text search:

              POST /-/v0/search  {
                searchQuery: { freetext: "how climb trees", lookWhere: { inCategories: [categoryX] },
                orderBy: 'PopularFirst',
                limit: 5,
              }
              
          2. In reply toKajMagnus:
            BCraig Bramscher @bramscher
              2020-04-25 06:26:07.677Z

              Hi! I am trying to use these instructions to conenct with a bubble.io instance. It has an api connector, which I have used for other integrations for SSO. However I can not seem to structure the json properly to have talkyard like the response.

              when i initialize the call, I get BAD REQUEST

              POST /-/v0/sso-upsert-user-generate-login-secret' [Expecting text/json or application/json body]

              I am wondering if I could connect using postman or another way to better troubleshoot this. Or maybe I can not use the standard API connection tools in bubble.io ?

              I am happen to share more details, if I could get it working with Bubble there would be many people that would like to follow my integration with their systems as a lot of people are going with discourse but not terribly happy.

              Thanks

              Craig

              1. KajMagnus @KajMagnus2020-04-25 12:07:21.860Z2020-04-25 12:14:19.531Z

                I replied here, in a new topic:
                https://www.talkyard.io/-380/how-use-talkyard-with-bubbleio — would you like to reply there please :- )

              2. In reply toKajMagnus:
                SAndrea Ghensi @sanzoghenzo
                  2021-03-15 11:57:57.268Z

                  Hi, I hope I'm not doing anything wrong by replying to this post instead of opening a new discussion...

                  I also would like to get an idea of what's it currently offered by the API.

                  To this day, the documentation category holds only a handful of pages regarding the authentication API and nothing more.

                  I saw that some work has been done to implement new API endpoints by looking at the ideas category, but I find it hard to search/get what I want.

                  These days is common to use something like SwaggerUI or Redoc to document the API and provide a quick way to test it.

                  Is there any chance you can add this feature?

                  Thanks for your great work!

                  1. KajMagnus @KajMagnus2021-03-21 08:13:07.815Z2021-03-21 08:27:28.870Z

                    Hi Andrea @sanzoghenzo (sorry for the late reply. I started reading about Redoc, and then I started doing some other things / got-distracted and didn't reply ... until now),

                    Redoc looks interesting. — What API endpoints would you be interested in? (Hmm, unless I was too slow with replying :- (.  Maybe then I could start with that.)

                    the documentation category holds only a handful of pages

                    Yes, and I'm a bit about to start to write documentation. Just recently I implemented sub categories, so that now there can be a Documentation category, with sub categories: How To:s, Tutorials, Reference, Theory.

                    1. SAndrea Ghensi @sanzoghenzo
                        2021-03-22 08:16:04.443Z

                        Hi @KajMagnus , thanks for the reply!

                        Honestly I don't know what I'm looking for, it was just to have a bird's eye view on what it could be possible with the API right now.

                        I'm trying to compare various Q&A platform and pick the one that gives us the most flexibility/integration ability with our current company infrastructure.

                        We use Google Workplace, so I was wondering about creating a Google Chat Bot for quick search and notification (something I've seen in Tettra's Slack integration).

                        Also. the ability to automatically create categories and/or tags when we start new projects would be great.

                        Thanks for the attention, keep up the good work!

                        1. Hi Andrea,

                          flexibility/integration ability

                          That works a bit (see below), and is next on the roadmap :- )  I mean outgoing webhooks: Talkyard Roadmap 2021

                          Chat Bot for quick search

                          There's a full-text-search API, so search results from Talkyard can be embedded in one's app / website / something.

                          notification

                          Some people recently built a chat bot that polls Talkyard for new notifications, via Ty's List API: API: Being able to fetch Topics based on answered state

                          (With outgoing web hooks, such notifications can be more real-time.)

                          automatically create categories and/or tags

                          There's an API for automatically creating new categories. Tags, though, are not currently supported (is on the roadmap).

                          1. Andrea @sanzoghenzo now there is some API docs in a new API docs category: https://www.talkyard.io/forum/latest/docs-api

                            Incl about how to automatically create pages and categories: How to Create Pages and Categories and Post Replies via API (however, just an end-to-end test link, currently, about upserting categories )