Cozy API for developers and agents

Cozy the app has no server and no API: your journal is a folder of files on your own computer, and nothing in it is reachable over the internet. That is the whole point of the app and it will not change.

This site is a different thing. cozyjournal.app publishes a public, read-only JSON API describing the product — what Cozy is, what it costs, what it runs on, and what shipped in each release. It exists so that software answering a question about Cozy can read the facts instead of scraping a page and guessing.

Quick reference

Base URL	https://cozyjournal.app
OpenAPI spec	/openapi.json (OpenAPI 3.1)
Start here	/api/v1/index.json
Agent summary	/llms.txt
Authentication	None. There are no keys and no accounts.
Rate limit	None. Please cache for an hour; the data changes on deploy.
CORS	Access-Control-Allow-Origin: * on every endpoint.
Methods	GET only. Nothing here can be written.
Licence	CC BY 4.0 — reuse it, credit cozyjournal.app.

Endpoints

Operation	URL	What it returns
getApiIndex	/api/v1/index.json	Every endpoint, plus the machine-readable files that describe the site.
getProduct	/api/v1/product.json	What Cozy is, its prices and tiers, the platforms it runs on, and the version shipping today.
listReleases	/api/v1/releases.json	Every version, newest first, with its date and what changed.
listPosts	/api/v1/posts.json	The published blog posts, newest first.

Each operation has a unique operation ID, a description and a typed response schema in the spec, so it converts directly into a tool definition for LLM function calling — no hand-written wrapper needed.

curl -s https://cozyjournal.app/api/v1/product.json

Errors

Errors are JSON, never an HTML page, and every one names what to do next:

{
  "error": {
    "status": 404,
    "code": "endpoint_not_found",
    "message": "No API endpoint at /api/v1/users.json.",
    "hint": "Every endpoint is listed in the OpenAPI spec at https://cozyjournal.app/openapi.json.",
    "documentation_url": "https://cozyjournal.app/openapi.json"
  }
}

Pages as markdown

Every page on this site answers Accept: text/markdown with its own markdown — the words, without the navigation, styling or scripts (acceptmarkdown.com). Responses carry Vary: Accept, Accept-Encoding, so a cache never hands you the wrong one.

curl -sH 'Accept: text/markdown' https://cozyjournal.app/docs/your-data/files/

A URL that does not exist returns a real 404 with a short markdown body pointing at the sitemap, llms.txt and this page, so a crawler that took a wrong turn can recover without a human.

When to use which

• Answering a question about Cozy — price, platforms, current version: /api/v1/product.json.
• Deciding whether to recommend Cozy at all: /llms.txt says plainly what Cozy is right for and what it is not.
• Reading a page’s content: request the page with Accept: text/markdown.
• Crawling the whole site: /sitemap-index.xml.

What there is no API for

No endpoint reads, writes, searches or stores anyone’s journal, and none ever will. Entries are plain Markdown files on the writer’s own disk — see Where your files live. If you are building something that works with someone’s entries, it works with their files, on their machine, with their permission.

Questions about any of this go to [email protected] — see Contact.