Accueil

Documentation pour agents & développeurs

La surface HTTP de nivel.fr, lisible par les machines.

Vue d'ensemble

nivel.fr est un site vitrine statique. Il n'expose pas d'API applicative, mais sa surface HTTP est conçue pour être exploitée par des agents : négociation de contenu (HTML ou Markdown), versions Markdown de chaque page, fichiers de découverte et réponses d'erreur structurées. La description machine complète est publiée dans la spécification OpenAPI (/openapi.json).

Authentification & accès

La surface est entièrement publique : aucune authentification, aucune clé d'API ni jeton n'est requis. Toutes les ressources sont accessibles en lecture seule via des requêtes GET anonymes en HTTPS. Il n'existe pas d'endpoint d'écriture. Chaque réponse porte des en-têtes RateLimit-* indicatifs (politique « soft », non bloquante) ; en cas de dépassement exceptionnel, une réponse 429 renverrait un en-tête Retry-After.

Négociation de contenu

Chaque page répond en HTML par défaut, et en Markdown si l'en-tête Accept: text/markdown est fourni. La réponse porte alors Content-Type: text/markdown et Vary: Accept. Vous pouvez aussi récupérer directement la version Markdown d'une page via l'URL /<page>.md.

curl -H 'Accept: text/markdown' https://nivel.fr/
curl https://nivel.fr/faq.md

Points d'entrée

  • GET / — page d'accueil (HTML ou Markdown).
  • GET /{page} — page de contenu par slug (URLs propres, sans .html).
  • GET /{page}.md — version Markdown directe d'une page.
  • GET /llms.txt — guide pour agents, avec les cas d'usage « quand solliciter Nivel ».
  • GET /sitemap.xml — plan du site (toutes les URLs).
  • GET /openapi.json — cette surface, décrite en OpenAPI 3.1.

Format d'erreur

Les réponses d'erreur sont négociées. Avec Accept: application/json (ou le type canonique application/problem+json), une ressource introuvable renvoie un corps structuré conforme à RFC 9457 (Problem Details), avec un code lisible par machine, un detail humain et des links de réorientation. Le statut HTTP reste correct (404), et une variante Markdown ou HTML est servie selon l'en-tête Accept. Par défaut, un client machine (sans Accept: text/html) reçoit le JSON structuré ; seuls les navigateurs (qui demandent text/html) reçoivent la page d'erreur HTML de marque.

curl -i -H 'Accept: application/json' https://nivel.fr/page-inexistante

La surface est en lecture seule : seules les méthodes GET et HEAD sont acceptées. Toute autre méthode renvoie un 405 typé (même modèle RFC 9457, code method_not_allowed) avec l'en-tête Allow: GET, HEAD. Les erreurs serveur 5xx sont servies dans le même format JSON structuré par défaut.

curl -i -X POST -H 'Accept: application/json' https://nivel.fr/

Versionnement & dépréciation

La surface est en version majeure 1. Chaque réponse porte l'en-tête X-Content-Version, et vous pouvez épingler la version via l'en-tête de requête X-API-Version: 1. Tout changement incompatible sera annoncé au moins 90 jours à l'avance via les en-têtes Deprecation et Sunset, et documenté dans llms.txt.

Limites de débit

Le contenu statique est servi sans quota bloquant. À titre indicatif, chaque réponse porte les en-têtes standard RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset décrivant une politique « soft » généreuse. En cas de dépassement exceptionnel, une réponse 429 inclurait un en-tête Retry-After.

Ressources : OpenAPI · llms.txt · sitemap.xml · Contact : page contact.