{
    "openapi": "3.1.0",
    "info": {
        "title": "musics.name public API",
        "version": "1.0.0",
        "description": "Read-only JSON access to every article, topic, tool and featured release published on musics.name. No authentication, no keys, CORS open. Article Markdown is also available directly at /articles/{slug}.md.",
        "contact": {
            "name": "Yunus Emre Vurgun",
            "url": "https://yunusemrevurgun.com/contact"
        },
        "license": {
            "name": "Content: attribution required",
            "identifier": "LicenseRef-Proprietary-Attribution"
        },
        "termsOfService": "https://musics.name/terms/"
    },
    "servers": [
        {
            "url": "https://musics.name",
            "description": "Production"
        }
    ],
    "paths": {
        "/api/index.json": {
            "get": {
                "summary": "Site index",
                "operationId": "getIndex",
                "responses": {
                    "200": {
                        "description": "Site metadata, counts, endpoints, latest articles.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/articles.json": {
            "get": {
                "summary": "Article list",
                "operationId": "listArticles",
                "parameters": [
                    {
                        "name": "topic",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Topic key, for example harmony."
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tag, lower case, for example cadence."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full-text filter over the same index as /api/search.json."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Article metadata list with totals and pagination link.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/article.json": {
            "get": {
                "summary": "One article",
                "operationId": "getArticle",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Article with headings, FAQ, Markdown source and rendered HTML.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown slug.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/topics.json": {
            "get": {
                "summary": "Topic taxonomy",
                "operationId": "listTopics",
                "responses": {
                    "200": {
                        "description": "Topics with counts and the newest article in each.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tools.json": {
            "get": {
                "summary": "Browser tools",
                "operationId": "listTools",
                "responses": {
                    "200": {
                        "description": "Tools with features, FAQ and schema.org nodes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/releases.json": {
            "get": {
                "summary": "Featured recordings",
                "operationId": "listReleases",
                "responses": {
                    "200": {
                        "description": "Releases with per-store links and cover art.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/search.json": {
            "get": {
                "summary": "Search articles",
                "operationId": "searchArticles",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ranked results with snippets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Query missing or shorter than two characters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/openapi.json": {
            "get": {
                "summary": "This document",
                "operationId": "getOpenApi",
                "responses": {
                    "200": {
                        "description": "OpenAPI description.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/articles/{slug}.md": {
            "get": {
                "summary": "Article Markdown source",
                "operationId": "getArticleMarkdown",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Raw Markdown with front matter.",
                        "content": {
                            "text/markdown": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown slug."
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "ArticleMeta": {
                "type": "object",
                "required": [
                    "slug",
                    "title",
                    "url"
                ],
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "dek": {
                        "type": "string"
                    },
                    "topic": {
                        "type": "string"
                    },
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "level": {
                        "type": "string",
                        "enum": [
                            "intro",
                            "intermediate",
                            "advanced"
                        ]
                    },
                    "date": {
                        "type": "string",
                        "format": "date"
                    },
                    "words": {
                        "type": "integer"
                    },
                    "reading_time_minutes": {
                        "type": "integer"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "markdown_url": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            }
        }
    },
    "x-policy": {
        "rate_limits": "None applied by the application; static hosting caching applies (max-age 300–3600).",
        "caching": "Responses are cacheable; ETag is not used, Last-Modified is used on HTML pages.",
        "attribution": "Quote articles with a link to their canonical URL. Reuse of full text requires permission.",
        "robots": "https://musics.name/robots.txt",
        "llms": "https://musics.name/llms.txt"
    }
}