jant-me/jant/docs

Jant Site Skill

This page is written for AI assistants working with one Jant site. Use it when the user asks you to read, publish, edit, organize, search, or migrate site content through Jant's HTTP API or MCP interface.

The full HTTP API reference lives at <https://jant.me/docs/API.md>. This skill explains how to choose the right interface, work safely, understand Jant's content model, and run common workflows. Consult the reference for complete request and response schemas instead of guessing fields.

Scope and Safety

• Use this skill only for the target site identified below. Do not substitute another site without the user's confirmation.
• Start with read-only inspection when the state of the site or the user's intent is unclear.
• Get explicit confirmation before bulk publishing, bulk deletion, destructive settings changes, or any action that is difficult to reverse. A request to perform a specific ordinary write, such as publishing one post, already supplies that confirmation.
• For uncertain or bulk content changes, ask whether to save posts as drafts or publish them immediately.
• Treat API tokens like passwords. Never log, commit, or repeat a token back to the user after they provide it.
• Use the public API or MCP interface. Do not edit the database directly and do not call /api/internal/*; those endpoints belong to the hosted control plane.
• Keep bulk writes sequential. Save returned IDs after each successful write so interrupted work can resume without creating duplicates.

Choose an Interface

Jant exposes the same site-owner capabilities through two interfaces:

For MCP, call initialize, then tools/list, and use the returned schemas rather than assuming tool arguments. The tool groups cover posts, Threads, media, attachments, Collections, settings, and search.

For HTTP, these are the main entry points:

Public post and Thread reads under /api/public/* can work without a token. A site can disable anonymous API reads; /api/public/* then becomes unavailable. Everything else, including search and Collection reads, requires authentication.

Confirm the Target and Authenticate

Before an authenticated or multi-step operation, confirm:

• The Jant site URL (e.g. https://example.com).
• The exact outcome the user wants, including which content may change.
• For bulk work, whether new posts should use status: "published" or status: "draft".

Have the user create an API token when the operation needs authentication:

1. Sign in to Jant at <site>/signin.
2. Open Settings → API Tokens.
3. Create a token and copy it immediately. It is shown only once.

Send the token as Authorization: Bearer jnt_....

export JANT_API_TOKEN=jnt_...
export JANT_SITE=https://example.com

Understand the Content Model

Jant is a single-author microblog. There are no users, comments, likes, followers, or social relationships to manage.

Three concepts shape almost every content operation:

1. Posts have three formats — note, link, and quote. Preserve the semantic format instead of coercing everything into note.
2. Threads connect posts — a reply is a post whose replyToId points to another post. There is no separate comments table. A post's threadPostCount says how many posts its Thread holds; read them all with GET /api/threads/:id/posts, passing any post's ID, rather than collecting replies from the post list.
3. Collections curate Threads — they are intentional groupings, not tags. A Thread can belong to multiple Collections; its root and replies share the same memberships.

note — original writing

Use for essays, journal entries, status updates, photo posts with captions, and other content written by the site owner.

• Required: format: "note"
• Recommended: bodyMarkdown
• Optional: title

link — a shared reference

Use when the post is fundamentally pointing readers to another resource.

• Required: format: "link", title, url
• Optional: bodyMarkdown for the owner's commentary

quote — a cited passage

Use when the post is built around someone else's words.

• Required: format: "quote", quoteText
• Optional: sourceName, sourceUrl, and bodyMarkdown for commentary
• Do not send title or url; quote posts use sourceName and sourceUrl instead.

Common Content Operations

Read the current state before modifying existing content. Use GET /api/posts/:id when you need fields that may not appear in a list response, including Thread-level Collection memberships.

Create a note with an explicit status and visibility:

curl -X POST "$JANT_SITE/api/posts" \
  -H "Authorization: Bearer $JANT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "note",
    "bodyMarkdown": "Hello from Jant.",
    "status": "published",
    "visibility": "public"
  }'

Use PUT /api/posts/:id to update a post and DELETE /api/posts/:id to delete one. Fetch the post first, preserve fields the user did not ask to change, and confirm before deletion. To edit a body, read it with GET /api/posts/:id?content=markdown (MCP: jant_posts_get with content: "markdown") and send the edited bodyMarkdown back; a text attachment's Markdown is at its contentUrl.

Use POST /api/upload for an ordinary single-file script or one-time migration. Use the session-based /api/uploads flow for large files, unreliable connections, or clients that need resumable transport. Save the returned med_* ID before attaching media to a post.

Use GET /api/settings before PUT /api/settings. Settings values are strings in the HTTP API; preserve settings outside the user's requested change.

For exact fields, filters, pagination, and response schemas, read the full HTTP API reference.

Import Content from Another Platform

Use this workflow when the user wants to move an old blog, site, or archive into this Jant site. The request may arrive as one sentence, with no export and no token yet. Lead the user through the rest.

Lead the user

Ask for one thing at a time, when the next step needs it. Name the menus the user clicks, not API endpoints.

1. Check that you can send HTTP requests to <site> and read files the user gives you. If you cannot, say so first and suggest an assistant that can, such as a coding agent with shell access. Do not hand over a script unless the user asks for one.
2. Ask which platform the old blog is on and where it lives.
3. Get the content. Use an export if the user has one. If not, tell them where their platform exports it (the table under "Read the source" lists the usual places) and wait for the file. When the old blog is public and its feed carries full posts, you can read the feed instead. Feeds usually hold only recent posts, so compare the count with the old blog's archive before relying on one.
4. Ask for the API token just before the first write, using the steps in "Confirm the Target and Authenticate". Do not ask for it at the start.

Plan before writing

1. Inspect the target site so you know whether it already contains content.
2. Inspect 3–5 representative source posts end to end before deciding how to transform anything.
3. Report what you found: source formats, item counts, dates, media, internal links, categories, and anything unsupported.
4. Ask how to handle ambiguous categories or tags. Map them to Collections, drop them, or fold them into post bodies only with the user's direction.
5. Agree on draft versus published status and on a duplicate policy before creating posts.
6. Build a resumable source-ID map and persist { sourceId -> jantId, slug } after every successful write.

A slug or path collision returns 409 CONFLICT, but that does not make an import automatically idempotent. Items with new or generated slugs can still be duplicated, so use the source-ID map rather than relying on conflicts.

Read the source

Common source shapes include:

Do not assume the source schema from the platform name alone. Check titles, bodies, dates, embedded media, internal links, categories, and source identifiers in real records.

Map source formats

Use these heuristics as a starting point:

• WordPress, Ghost, and Substack standard posts → note with title and bodyMarkdown.
• Linklog posts that are primarily an external URL plus commentary → link.
• WordPress or Tumblr quote posts → quote.
• Tumblr photo posts with captions → note with uploaded images.
• Tumblr link posts → link.
• Reblogs or reposts → ask the user. Jant has no native reblog concept; quote with sourceUrl is often the closest representation.

When uncertain, prefer note. Turning a real link or quote into a note loses semantic information, while turning original writing into a link or quote invents structure.

Convert bodies to Markdown

Send bodyMarkdown, not body. The body field expects TipTap JSON and is intended for editor integrations.