{
  "openapi": "3.1.0",
  "info": {
    "title": "Cozy public API",
    "version": "1.0.0",
    "summary": "Read-only facts about Cozy, the local-first journaling app.",
    "description": "A public, unauthenticated, read-only API describing Cozy: what the app is,\nwhat it costs, what shipped in each release, and what has been written\nabout it. Use it to answer questions about Cozy, to check the current\nversion, or to link a person to the right page.\n\nEvery response is a static JSON document rebuilt with the site, so there\nis no key, no quota and no rate limit. All endpoints are GET only.\n\nIt does not read, write or store anyone's journal. Cozy keeps entries as\nplain files on the owner's own computer, and no server ever sees them.",
    "contact": {
      "name": "Alberto Gallego",
      "email": "dear@cozyjournal.app",
      "url": "https://cozyjournal.app"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://cozyjournal.app",
      "description": "Production"
    }
  ],
  "security": [],
  "externalDocs": {
    "url": "https://cozyjournal.app/llms.txt",
    "description": "Cozy in one file, for agents"
  },
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "List the endpoints of this API",
        "description": "Returns the name and URL of every endpoint, plus links to the machine-readable files that describe the site (llms.txt, the sitemap, this spec). Start here when discovering the API.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/product.json": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get what Cozy is, what it costs and what it runs on",
        "description": "Returns the product facts: the pitch, the platforms and their minimum OS versions, the one-time prices in USD, the update policy, the privacy guarantees, the current shipping version, and where to buy or download. Use this to answer 'what is Cozy', 'how much is Cozy', 'does Cozy run on Windows' or 'does Cozy have a subscription'.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/releases.json": {
      "get": {
        "operationId": "listReleases",
        "summary": "List every released version, newest first",
        "description": "Returns every Cozy release with its version, release date, the platforms it shipped to, its headline, and a link to its section of the changelog. The latest version per platform is repeated under `latest`. Use this to check whether a version is current or to summarise what changed.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReleaseList"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts.json": {
      "get": {
        "operationId": "listPosts",
        "summary": "List the published blog posts, newest first",
        "description": "Returns every published post on the Cozy blog with its title, description, publication date and URL. Drafts and future-dated posts are excluded. Each URL also serves markdown to a request sending `Accept: text/markdown`.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostList"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiIndex": {
        "type": "object",
        "required": [
          "name",
          "version",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of this API."
          },
          "version": {
            "type": "string",
            "description": "API version, e.g. \"v1\"."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "URL of this OpenAPI document."
          },
          "endpoints": {
            "type": "array",
            "description": "Every endpoint in this version of the API.",
            "items": {
              "type": "object",
              "required": [
                "operationId",
                "url",
                "description"
              ],
              "properties": {
                "operationId": {
                  "type": "string",
                  "description": "Matches the operationId in the spec."
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "files": {
            "type": "object",
            "description": "Machine-readable files describing the site itself.",
            "properties": {
              "llms_txt": {
                "type": "string",
                "format": "uri"
              },
              "sitemap": {
                "type": "string",
                "format": "uri"
              },
              "robots_txt": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "name",
          "summary",
          "url",
          "platforms",
          "pricing"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "description": "One paragraph on what Cozy is."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "type": "string",
            "description": "What kind of app this is."
          },
          "maker": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "email": {
                "type": "string",
                "format": "email"
              }
            }
          },
          "platforms": {
            "type": "array",
            "description": "Where Cozy runs, with the minimum OS version.",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "minimumOs",
                "available"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "mac",
                    "windows",
                    "ios",
                    "android",
                    "linux"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "minimumOs": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "available": {
                  "type": "boolean",
                  "description": "False for platforms not shipped yet."
                },
                "download": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uri"
                }
              }
            }
          },
          "pricing": {
            "type": "object",
            "required": [
              "model",
              "currency",
              "options"
            ],
            "properties": {
              "model": {
                "type": "string",
                "enum": [
                  "one-time"
                ],
                "description": "Cozy has no subscription."
              },
              "currency": {
                "type": "string",
                "description": "ISO 4217 code."
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "price"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number",
                      "description": "Tax-exclusive price."
                    },
                    "covers": {
                      "type": "string"
                    },
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri"
                    }
                  }
                }
              },
              "updatePolicy": {
                "type": "string"
              },
              "studentDiscountPercent": {
                "type": "integer"
              }
            }
          },
          "privacy": {
            "type": "object",
            "description": "The guarantees Cozy is built on.",
            "properties": {
              "account": {
                "type": "boolean",
                "description": "Whether an account is required."
              },
              "cloudStorage": {
                "type": "boolean",
                "description": "Whether entries are stored on a server."
              },
              "aiTraining": {
                "type": "boolean",
                "description": "Whether entries are used for AI."
              },
              "worksOffline": {
                "type": "boolean"
              },
              "fileFormat": {
                "type": "string",
                "description": "How entries are stored on disk."
              }
            }
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "latestVersion": {
            "type": "object",
            "description": "Current shipping version per version line.",
            "properties": {
              "desktop": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ios": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            },
            "description": "Canonical URLs: download, pricing, docs, changelog, blog, support."
          }
        }
      },
      "Release": {
        "type": "object",
        "required": [
          "version",
          "platforms",
          "url"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Semantic version, e.g. \"1.2.7\"."
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Headline for the release."
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Release date, ISO 8601."
          },
          "platforms": {
            "type": "array",
            "description": "Which platforms this version shipped to.",
            "items": {
              "type": "string",
              "enum": [
                "mac",
                "windows",
                "ios"
              ]
            }
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "This release's section of the changelog."
          }
        }
      },
      "ReleaseList": {
        "type": "object",
        "required": [
          "releases",
          "latest"
        ],
        "properties": {
          "releases": {
            "type": "array",
            "description": "Every release, newest first.",
            "items": {
              "$ref": "#/components/schemas/Release"
            }
          },
          "latest": {
            "type": "object",
            "description": "Current version per version line. Desktop and iOS number separately.",
            "properties": {
              "desktop": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ios": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "count": {
            "type": "integer",
            "description": "Number of releases returned."
          }
        }
      },
      "Post": {
        "type": "object",
        "required": [
          "title",
          "url",
          "date"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PostList": {
        "type": "object",
        "required": [
          "posts"
        ],
        "properties": {
          "posts": {
            "type": "array",
            "description": "Published posts, newest first.",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code."
              },
              "code": {
                "type": "string",
                "description": "Stable machine-readable code.",
                "enum": [
                  "endpoint_not_found",
                  "not_acceptable"
                ]
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "How to fix the request."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}