{ "openapi": "3.1.0", "info": { "title": "404 Mates Publication API", "version": "1.3.0", "description": "API de rédaction 404 Mates (create/update/publish sans gate QC).\nAuth: Bearer MATES_API_KEY ou x-api-key.\n\n## Versioning\nSurface stable : `/api/v1/mcp/*` (alias de `/api/mcp/*`).\nEn-tête de réponse `API-Version: 1`.\n\n## Deprecation policy\nLes breaking changes passent par une nouvelle version d’URL (`/api/v2/...`).\nAvant retrait d’une version, les réponses concernées exposent `Deprecation` et `Sunset` (RFC 8594) pendant au moins 90 jours.\nAnnonces : /developers et /llms.txt.\n\n## Rate limits\nEn-têtes `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (et `Retry-After` sur 429).\nLimite indicative : 120 req/min par clé." }, "servers": [ { "url": "https://404mates.ai", "description": "Production (chemins absolus /api/mcp et /api/v1/mcp)" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "MATES_API_KEY. Dans ChatGPT : Authentification = Clé API / Bearer, coller uniquement la clé (sans « Bearer »)." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative à Bearer (whitelist Claude Connectors)." } }, "schemas": { "ArticleInput": { "type": "object", "required": [ "title", "slug", "body_markdown" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "slug": { "type": "string", "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "URL /articles/{slug}" }, "body_markdown": { "type": "string", "description": "Corps markdown (H2/H3, listes, liens)" }, "excerpt": { "type": "string", "maxLength": 500 }, "brief_markdown": { "type": "string", "description": "Bloc En bref" }, "analyse_404mates_markdown": { "type": "string", "description": "Lecture 404 Mates (optionnel)" }, "seo_title": { "type": "string", "maxLength": 70 }, "seo_description": { "type": "string", "maxLength": 160 }, "category_slug": { "type": "string", "description": "Slug catégorie (listCategories / getSchema) — obligatoire pour publier" }, "author_slug": { "type": "string", "description": "Slug auteur éditorial (listAuthors / getSchema.authors) — obligatoire pour publier." }, "sources_json": { "type": "array", "items": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "status": { "type": "string", "enum": [ "drafting", "review", "published" ], "default": "review" } } }, "ArticleUpdate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 200 }, "slug": { "type": "string", "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "body_markdown": { "type": "string" }, "excerpt": { "type": "string", "maxLength": 500 }, "brief_markdown": { "type": "string" }, "analyse_404mates_markdown": { "type": "string" }, "seo_title": { "type": "string", "maxLength": 70 }, "seo_description": { "type": "string", "maxLength": 160 }, "category_slug": { "type": "string" }, "author_slug": { "type": "string" }, "sources_json": { "type": "array", "items": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "status": { "type": "string", "enum": [ "drafting", "review", "published" ] } }, "description": "Mise à jour partielle sans QC : envoyer uniquement les champs à modifier." }, "PublishInput": { "type": "object", "additionalProperties": false, "properties": { "author_slug": { "type": "string", "description": "À fournir si l’article n’a pas encore d’auteur" }, "category_slug": { "type": "string", "description": "À fournir si l’article n’a pas encore de catégorie" } } }, "Article": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "drafting", "review", "published", "scheduled", "draft_unverified" ] }, "body_markdown": { "type": "string" }, "excerpt": { "type": "string", "nullable": true }, "seo_title": { "type": "string", "nullable": true }, "seo_description": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "title", "slug", "status" ] }, "ArticleEnvelope": { "type": "object", "required": [ "article" ], "properties": { "article": { "$ref": "#/components/schemas/Article" } } }, "ArticleList": { "type": "object", "properties": { "articles": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "CategoryList": { "type": "object", "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }, "Author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "specialty": { "type": "string" } } }, "AuthorList": { "type": "object", "properties": { "authors": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } } }, "SchemaResponse": { "type": "object", "properties": { "articleCreate": { "type": "object" }, "articleUpdate": { "type": "object" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "authors": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } } }, "ApiError": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Message humain (stable pour les clients legacy)" }, "code": { "type": "string", "description": "Code machine-readable", "enum": [ "not_found", "unauthorized", "validation", "conflict", "rate_limited", "internal" ] }, "hint": { "type": "string", "description": "Piste de résolution pour un agent" } } }, "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Message humain (stable pour les clients legacy)" }, "code": { "type": "string", "description": "Code machine-readable", "enum": [ "not_found", "unauthorized", "validation", "conflict", "rate_limited", "internal" ] }, "hint": { "type": "string", "description": "Piste de résolution pour un agent" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/api/mcp/schema": { "get": { "operationId": "getSchema", "summary": "Contraintes create/update + catégories + auteurs", "responses": { "200": { "description": "Schéma, catégories, auteurs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/mcp/categories": { "get": { "operationId": "listCategories", "summary": "Liste des catégories éditoriales", "responses": { "200": { "description": "Catégories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/mcp/authors": { "get": { "operationId": "listAuthors", "summary": "Liste des auteurs / personas éditoriaux", "responses": { "200": { "description": "Auteurs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/mcp/articles": { "get": { "operationId": "listArticles", "summary": "Liste des articles", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "drafting", "review", "published" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "operationId": "createArticle", "summary": "Créer un article", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleInput" } } } }, "responses": { "200": { "description": "Article créé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Slug déjà utilisé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/mcp/articles/{id}": { "get": { "operationId": "getArticle", "summary": "Article par ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "operationId": "updateArticle", "summary": "Mettre à jour un article (partiel)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleUpdate" } } } }, "responses": { "200": { "description": "Mis à jour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Slug déjà utilisé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/mcp/articles/{id}/publish": { "post": { "operationId": "publishArticle", "summary": "Publier un article (sans QC)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishInput" } } } }, "responses": { "200": { "description": "Publié", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Auteur ou catégorie manquant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/schema": { "get": { "operationId": "v1_getSchema", "summary": "Contraintes create/update + catégories + auteurs", "responses": { "200": { "description": "Schéma, catégories, auteurs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/categories": { "get": { "operationId": "v1_listCategories", "summary": "Liste des catégories éditoriales", "responses": { "200": { "description": "Catégories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/authors": { "get": { "operationId": "v1_listAuthors", "summary": "Liste des auteurs / personas éditoriaux", "responses": { "200": { "description": "Auteurs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/articles": { "get": { "operationId": "v1_listArticles", "summary": "Liste des articles", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "drafting", "review", "published" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "operationId": "v1_createArticle", "summary": "Créer un article", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleInput" } } } }, "responses": { "200": { "description": "Article créé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Slug déjà utilisé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/articles/{id}": { "get": { "operationId": "v1_getArticle", "summary": "Article par ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "operationId": "v1_updateArticle", "summary": "Mettre à jour un article (partiel)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleUpdate" } } } }, "responses": { "200": { "description": "Mis à jour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Slug déjà utilisé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/mcp/articles/{id}/publish": { "post": { "operationId": "v1_publishArticle", "summary": "Publier un article (sans QC)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishInput" } } } }, "responses": { "200": { "description": "Publié", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleEnvelope" } } } }, "400": { "description": "Auteur ou catégorie manquant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Clé invalide ou manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Ressource introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Erreur serveur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } } }