{
	"openapi": "3.1.0",
	"info": {
		"title": "HomeLab Guides posts API",
		"version": "1.0.0",
		"license": {
			"name": "CC BY 4.0",
			"url": "https://creativecommons.org/licenses/by/4.0/"
		},
		"description": "Project guides and notes from a self-hosted home. Read-only: lists the guides and notes, and gives each one as plain Markdown. Static files, no authentication. Human-readable docs: https://blog.jacq.cc/api/"
	},
	"servers": [
		{
			"url": "https://blog.jacq.cc"
		}
	],
	"paths": {
		"/api/v1/": {
			"get": {
				"operationId": "getApiIndex",
				"summary": "This list of endpoints",
				"responses": {
					"200": {
						"description": "Endpoints with their URLs",
						"content": {
							"application/json": {
								"schema": {
									"type": "object"
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/posts.json": {
			"get": {
				"operationId": "listPosts",
				"summary": "List every guide and note",
				"description": "Guides first (most recently updated first), then notes (newest first).",
				"responses": {
					"200": {
						"description": "All posts",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PostList"
								}
							}
						}
					}
				}
			}
		},
		"/{kind}/{slug}.md": {
			"get": {
				"operationId": "getPostMarkdown",
				"summary": "One post as plain Markdown",
				"description": "Same text as the web page, with its dates, links and change history. Use the markdown_url from listPosts.",
				"parameters": [
					{
						"name": "kind",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string",
							"enum": [
								"guides",
								"notes"
							]
						}
					},
					{
						"name": "slug",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string",
							"pattern": "^[a-z0-9-]+$"
						},
						"example": "gamesir-t1d-linux-gamepad"
					}
				],
				"responses": {
					"200": {
						"description": "The post",
						"content": {
							"text/markdown": {
								"schema": {
									"type": "string"
								}
							}
						}
					},
					"404": {
						"description": "No such post"
					}
				}
			}
		},
		"/llms.txt": {
			"get": {
				"operationId": "getLlmsTxt",
				"summary": "llms.txt index of the site",
				"responses": {
					"200": {
						"description": "Markdown index with a link per post",
						"content": {
							"text/plain": {
								"schema": {
									"type": "string"
								}
							}
						}
					}
				}
			}
		},
		"/llms-full.txt": {
			"get": {
				"operationId": "getAllPosts",
				"summary": "Every post in one Markdown file",
				"responses": {
					"200": {
						"description": "All posts, separated by ---",
						"content": {
							"text/plain": {
								"schema": {
									"type": "string"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"PostList": {
				"type": "object",
				"required": [
					"site",
					"title",
					"description",
					"count",
					"posts"
				],
				"properties": {
					"site": {
						"type": "string",
						"format": "uri"
					},
					"license": {
						"type": "object",
						"description": "The content licence, and the credit to give",
						"properties": {
							"name": {
								"type": "string"
							},
							"url": {
								"type": "string",
								"format": "uri"
							},
							"credit": {
								"type": "string"
							},
							"details": {
								"type": "string",
								"format": "uri"
							}
						}
					},
					"title": {
						"type": "string"
					},
					"description": {
						"type": "string"
					},
					"count": {
						"type": "integer"
					},
					"posts": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/Post"
						}
					}
				}
			},
			"Post": {
				"type": "object",
				"required": [
					"id",
					"kind",
					"title",
					"description",
					"url",
					"markdown_url",
					"published",
					"updated",
					"changes",
					"discussion"
				],
				"properties": {
					"id": {
						"type": "string",
						"example": "guides/gamesir-t1d-linux-gamepad"
					},
					"kind": {
						"type": "string",
						"enum": [
							"guide",
							"note"
						],
						"description": "Guides are kept up to date; notes are written once."
					},
					"title": {
						"type": "string"
					},
					"description": {
						"type": "string"
					},
					"url": {
						"type": "string",
						"format": "uri",
						"description": "Web page"
					},
					"markdown_url": {
						"type": "string",
						"format": "uri",
						"description": "The post as plain Markdown"
					},
					"published": {
						"type": "string",
						"format": "date"
					},
					"updated": {
						"type": "string",
						"format": "date"
					},
					"changes": {
						"type": "array",
						"description": "Updates a reader would care about, newest first",
						"items": {
							"type": "object",
							"required": [
								"date",
								"note"
							],
							"properties": {
								"date": {
									"type": "string",
									"format": "date"
								},
								"note": {
									"type": "string"
								}
							}
						}
					},
					"discussion": {
						"type": "object",
						"properties": {
							"hacker_news": {
								"type": "string",
								"format": "uri"
							},
							"lobsters": {
								"type": "string",
								"format": "uri"
							}
						}
					},
					"cover": {
						"type": "object",
						"description": "The picture shown next to the post on the home page (a drawing or a photo)",
						"required": [
							"url",
							"alt"
						],
						"properties": {
							"url": {
								"type": "string",
								"format": "uri"
							},
							"alt": {
								"type": "string",
								"description": "What the picture shows"
							}
						}
					}
				}
			}
		}
	}
}