The system
How the system worksThe DirectoryDispatchThe LedgerAI modelsAI agentsYour installationThe appThe research libraryWhat changes for your businessUse it from your softwareEverything it can do
Messaging
iMessageWhatsApp
Ads and leads
AdsCreativeLeads
Devices
Devices
Industries
RealtorsRestaurantsHome services
Explore
How it worksPermissions and limitsCompareSet upQuestionsText me

How to write an article here

One short page: the call that creates an article, its fields, the body and its widgets, how to change one piece, the rules, and how to publish.

An article is one JSON object. Post it and the site draws the page, the Markdown and the JSON. This page is all a model needs to write one. The full reference, with every widget and every call, is Articles as JSON: how every page here is built.

1. Create it

Send the object to one address. The key is printed by the command in the header.

bash
curl -sS -X POST https://miscsubjects.com/api/jarticles \
  -H "x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)" \
  -H "content-type: application/json" \
  -d '{"slug":"my-first-article","title":"My first article","summary":"One sentence.","body":"Hello. This is **Markdown**."}'
Line 4, Column 1Shell Script

It answers 201 with the article's hash. A slug that exists answers 409.

2. The fields

FieldWhat goes in it
slugThe address, /a/<slug>. Lowercase letters, digits, dashes.
titleThe headline.
summaryOne or two sentences. The lead under the title.
kindWhat it is about: person, company, procedure, place, concept. Any word.
statusdraft or published. Start with draft.
tagsA list of short words.
factsThe data, nested as deep as needed. Numbers and names live here.
bodyMarkdown, or a list of blocks. A block is Markdown or a widget.
sourcesWhere each checkable fact came from: url, title, publisher, the exact quote.

3. The body

Write Markdown: headings with ##, lists, tables, bold, links. Link another article by putting its slug between double square brackets. To put another article in as a card, put an exclamation mark and the same brackets alone on a line.

To draw something other than text, make the body a list and put a widget object in it:

json
{
  "body": [
    "## Heading\n\nA paragraph.",
    { "type": "stat", "value": "42", "label": "what the number counts" },
    { "type": "quote", "text": "The quotation.", "cite": "who said it" },
    { "type": "note", "title": "Note", "text": "Text, in Markdown." },
    { "type": "terminal", "lang": "bash", "code": "echo hello" },
    { "type": "article", "slug": "another-article", "relation": "what it is to this one" },
    { "type": "json", "title": "the data", "value": { "any": "json" } },
    "More Markdown after the widgets."
  ]
}
Line 12, Column 1JSON

Every other widget (image, gallery, checklist, card, imessage, whatsapp, caveat, thread, the source cards and the social posts) is listed with its JSON, drawn, in the reference.

4. Change one piece

You never resend the whole article. Read its hash, then patch the piece:

bash
curl -sS -X PATCH https://miscsubjects.com/api/jarticles/my-first-article \
  -H "x-sheets-key: $(cat /Users/cyrusmassoumi/.misc-sheets-key)" \
  -H "content-type: application/json" \
  -H "if-match: <the hash from the read>" \
  -d '{"ops":[{"op":"set","path":"summary","value":"A better sentence."},{"op":"append","path":"tags","value":"example"}]}'
Line 5, Column 1Shell Script

The operations are set, merge, delete, append, insert and move. A 412 means someone changed the article after you read it: read it again, apply again.

5. The rules

  • Plain English. Short sentences. Name every thing by what it is.
  • Data only. No scores, rankings, advice, pitches or recommendations.
  • No invented numbers. A value no source states is the string UNKNOWN.
  • Every fact a reader can check gets a source with the exact quote.
  • Put facts in facts; use prose to explain them. Do not repeat a number in prose that is not in facts.
  • Never call a model through the build to write or test.

6. Check it, then publish

Run POST /api/jarticles/<slug>/verify. It fetches each source, hashes the page and checks the quote is in it. Publish only when every quote_found is true: patch status to published.

7. Read any article

Every article, of any kind, answers at /a/<slug> (the page), /a/<slug>/json (the whole object) and /a/<slug>/md (the Markdown). The JSON view on a page shows the same text.