# hereyougo: X (Twitter) bookmarks import format

Produce one JSON document listing X posts to save as bookmarks. Upload it on /import
(signed in). Either a JSON array of post objects, or an object {"bookmarks": [ ... ]}.

## One object per post

Only "url" is required. Leave out anything you don't know; never invent values.

- id (string): the post's numeric ID, as a string. Used to skip posts already imported.
  If missing, the URL is used instead.
- url (string, required): the post's address, https://x.com/<username>/status/<id>.
- text (string): the full post text, verbatim, with line breaks as \n. Don't summarise.
- created_at (string): when it was posted, ISO 8601 in UTC, e.g. "2024-09-13T14:12:32.000Z".
- lang (string): language code, e.g. "en".
- author (object): {"id": string, "username": string without @, "name": display name}.
- public_metrics (object): {"like_count", "repost_count", "reply_count", "bookmark_count"}, numbers.
- entities.hashtags (array): [{"tag": "craft"}] without the #. They become tags (lowercased).
- entities.urls (array): one per link in the text:
  {"url": the t.co link as it appears in text, "expanded_url": where it really goes,
   "title": page title, "description": page description, "display_url": shortened label}.
  t.co links in text are replaced by their expanded_url. Links back to x.com, twitter.com,
  t.co or twimg.com are dropped; the rest are shown as the post's outbound links.
- media (array): [{"type": "photo" | "video" | "animated_gif", "url": image URL}].
  For videos, give the preview image as "url" (or as "preview_image_url").
- article_title (object): {"title": ...} for an X Article; it becomes the bookmark's title.
- folders (array of strings): folder names, kept as written.

## Rules

- Output valid JSON only: UTF-8, double quotes, no comments, no trailing commas.
- One object per post, no duplicates. Order doesn't matter.
- Use the post's real ID and URL; if you only have the URL, the ID is its last path part.
- Keep text exactly as posted (emoji and line breaks included).

## What the import does with it

- Every imported X post is private, and only posts not already saved are added
  (by id, or by URL across all sources), so importing the same file twice is safe.
- The title is the article title, else the first link's title, else the first line of
  the text, else "Post by @username".

## Example

[
  {
    "id": "1834567890123456789",
    "url": "https://x.com/alice/status/1834567890123456789",
    "text": "Great essay on slow software https://t.co/AbC123 #craft\nWorth a read.",
    "created_at": "2024-09-13T14:12:32.000Z",
    "lang": "en",
    "author": {
      "id": "12345",
      "username": "alice",
      "name": "Alice Example"
    },
    "public_metrics": {
      "like_count": 1906,
      "repost_count": 246,
      "reply_count": 21,
      "bookmark_count": 310
    },
    "entities": {
      "hashtags": [
        {
          "tag": "craft"
        }
      ],
      "urls": [
        {
          "url": "https://t.co/AbC123",
          "expanded_url": "https://example.com/slow-software",
          "title": "In praise of slow software",
          "description": "An essay.",
          "display_url": "example.com/slow-software"
        }
      ]
    },
    "media": [
      {
        "type": "photo",
        "url": "https://pbs.twimg.com/media/Abc123.jpg"
      }
    ],
    "folders": [
      "Reading"
    ]
  }
]