Creating a new card, both top-level and card id required

Developers
1

Hi,

I am trying to develop a simple command line tool that quickly creates a new card. Something like this:

create-card "This is the title" <<EOM
# Header

This is the *body*.
EOM

I already understand that I will have to do the markdown to HTML conversion myself, but using Pandoc that will be alright.

I’m hoping to get a bit of help with understanding the request itself:

First of all, about the id fields:

  • Why is both a top-level id and a card id required?
  • Are they UUIDs as the example suggests?
  • Should these be randomly generated on the client?
  • What happens if I reuse an existing id, will that card be overwritten?

Also, I captured a network request from the webapp itself:

{
    "id": "92d63117-0766-4b49-9925-81375a2a2b38",
    "perms": 67108863,
    "personal_tags": [],
    "color": null,
    "created_when": "2021-01-17T21:25:13.059Z",
    "visited_when": null,
    "status": 2,
    "card": {
        "id": "37252463-4fbb-4f38-88a9-e0a9aca4d61f",
        "name": "This is a test",
        "markup": "Test Test\n## Test test\nTest *test* **test**",
        "html": "<p>Test Test</p>\n<h2>Test test</h2>\n<p>Test <em>test</em> <strong>test</strong></p>\n",
        "favorite": false,
        "tags": [],
        "backlinks": [],
        "created_when": "2021-01-17T21:25:13.059Z",
        "modified_when": null,
        "synced_when": null,
        "status": 2,
        "liked": false
    },
    "parent_links": []
}

I don’t understand a couple of these properties, can you explain them?

  • Status (twice)
  • Perms

Best,
Joost

2

The first thing to note is that there are two objects at play here: the first level, which is your access to the card (called a membership) and the card itself (common to all users with access to it), which is the sub-section keyed by card.

ID questions

  1. The top level ID is the ID of your membership, card.id is the ID of the card.
  2. They are indeed UUIDs – UUID v4.
  3. Yes.
  4. No, an error will occur telling you this card or membership already exists.

Request fields:

  • status: at the root (membership) level, this is whether the card is kept (2), unkept (1), pending (0), or junked (-1). At the card level this is only used internally.
  • perms: your permission on the card. This is handled by the backend system, so when you create a card, anything you put here will be discarded and replaced with Author permissions.

Hope that makes everything a bit clearer.

But yes, the UX of the API is something we are actively working on, so always open to suggestions if you find anything too cumbersome. Luckily the requirement to do your own markdown parsing is going away as part of the transition to the new WYSIWYG editor.

3

Thanks, Connor, this is very helpful.