No internet connection
  1. Home
  2. Documentation
  3. API

How to Create Pages and Categories and Post Replies via API

By KajMagnus @KajMagnus2021-05-22 18:11:04.433Z2021-10-05 05:15:16.072Z

[Update, 2021-11-05] This API, /-/v0/upsert-simple, is now a bit deprecated. Instead, there's a new Do API, at /-/v0/do, via which you'll be able to create pages and replies. And you can do other things too, e.g. having someone Like an idea and subscribe to it, see: How to Like and Subscribe to Pages via the API. [/Update]

Via Talkyard's Upsert API, you can create pages, categories and replies. (Editing / updating pages via API: Not yet supported.)

First, read about the Talkyard API authentication, including about how to enable the API.

And check out the API shorthand syntax.

External IDs and references

Below, you'll see fields like extId: ... and categoryRef: ... and authorRef: 'username:...'. What's that?

Well, Talkyard needs to know if, later on when you call the API again, if you're referring to the same thing. Because maybe you don't want to create a new page — maybe you instead want to update a page you've created already. Therefore you can specify your own IDs — and, from Talkyard's perspective, these IDs aren't Ty's own; they are "external" ids.

So, when you create a page, you specify extId: "aaa" — then, to update that page, call upsert-simple again with the same extId: "aaa".

Also, if you've created your own categories, you can give them your own "external ID".
And when creating a page, to choose in which category to place it, use the categoryRef field ("ref" here means "reference", — you're referencing a category, rather than including it inline).

For example, categoryRef: "extid:your-category-id". Note that the category ID is prefixed with extid:, so Talkyard knows what type of ID follows. Because in some cases, maybe it's more nice to use Talkyard's internal ids, instead of your own. (Then the prefix would probably be tyid: (for Talkyard ID))

And here: authorRef: 'username:some_username' the prefix username: tells Talkyard that what follows is someone's unique username — but you could also do: authorRef: 'extid:user_external_id' if you'd rather reference users, via their IDs in your database, than via usernames.

Creating Pages via API

POST /-/v0/upsert-simple  {
  pages: PageToUpsert[],
}

interface PageToUpsert {
  // id: Internal ID generated by the server
  extId: `${ups_page_ext_id}`,
  pageType: PageType,
  categoryRef: `extid:${category_ext_id}`,
  authorRef: `username:${some_username}`,
  title: St,
  // slug: generated by the server, derived from the title
  body: St,
  bodyMarkupLang?: 'HTML',   // default is CommonMark
}

const enum PageType {
  Question = 10,
  Problem = 14,
  Idea = 15,
  Discussion = 12,
}

By setting categoryRef and authorRef to the appropriate values, you can choose in which category it'll appear, and who the author will be.

End-to-end tests

If you'd like to see some code:

Posting Replies via API

Todo: Write docs

End-to-end tests

Creating Categories via API

Todo: Write docs

End-to-end tests

  • 0 replies