API Kreafy

L'API publique de Kreafy : spécification OpenAPI, endpoints, négociation Markdown et ressources pour agents. Sans clé, sans compte.

Kreafy publie une API publique en lecture seule. Elle expose tout ce dont un développeur ou un agent IA a besoin pour répondre à une question sur le produit : la documentation, le changelog, les cas d'usage, et une recherche plein texte sur la documentation.

Pas de clé d'API, pas de compte, pas d'inscription. Tous les endpoints ci-dessous répondent à un simple GET.

Les ressources en un coup d'œil

Ressource	URL
Spécification OpenAPI 3.1	`/openapi.json` (aussi `/openapi.yaml`)
Index de l'API	`/api/v1`
Carte pour agents	`/llms.txt`
Consignes pour agents	`/.well-known/agent-instructions.md`
Toute la doc en un fichier	`/llms-full.txt`
Sitemap	`/sitemap.xml`

Endpoints

URL de base : https://kreafy.lyrad.dev. Toutes les réponses sont en JSON, UTF-8.

Opération	Méthode et chemin	À quoi ça sert
`getApiIndex`	`GET /api/v1`	Découvrir la surface de l'API.
`getServiceHealth`	`GET /api/v1/health`	Vérifier que le service répond.
`listDocumentationPages`	`GET /api/v1/docs`	Le plan de la documentation.
`getDocumentationPage`	`GET /api/v1/docs/{slug}`	Une page, en Markdown.
`searchDocumentation`	`GET /api/v1/search?q=`	Partir d'une question.
`listChangelogEntries`	`GET /api/v1/changelog`	Les nouveautés, récentes d'abord.
`listSolutions`	`GET /api/v1/solutions`	Les cas d'usage par métier.

Chaque opération accepte ?locale=fr ou ?locale=en. L'anglais est la valeur par défaut.

Exemple

curl -s "https://kreafy.lyrad.dev/api/v1/search?q=credits&locale=fr"
curl -s "https://kreafy.lyrad.dev/api/v1/docs/facturation/credits?locale=fr"
curl -s -H "Accept: text/markdown" "https://kreafy.lyrad.dev/api/v1/docs/facturation/credits"

Erreurs

Les erreurs sont en JSON, jamais en HTML, et prennent toujours la même forme :

{
  "error": {
    "code": "not_found",
    "message": "Aucune page de documentation à « guides/inexistant ».",
    "hint": "Appelle https://kreafy.lyrad.dev/api/v1/docs pour la liste des chemins valides.",
    "status": 404,
    "documentation": "https://kreafy.lyrad.dev/docs/api",
    "details": { "requested": "guides/inexistant" }
  }
}

Branchez-vous sur code, pas sur message : les codes sont stables, les messages sont écrits pour des humains et peuvent être réécrits. La liste des codes est dans la spécification OpenAPI, sous le schéma Error.

Négociation de contenu Markdown

Toutes les pages publiques du site répondent en Markdown si la requête le demande, selon la convention acceptmarkdown.com :

curl -s -H "Accept: text/markdown" https://kreafy.lyrad.dev/fr

Les réponses portent Vary: Accept, Accept-Encoding, pour qu'un CDN ne serve jamais la variante HTML à un client qui demande du Markdown. Une requête n'acceptant ni text/html ni text/markdown reçoit un 406 avec un corps JSON qui liste les formats disponibles.

Les pages de doc ont en plus une URL Markdown permanente : ajoutez .mdx à l'URL de n'importe quelle page, par exemple /fr/docs/prise-en-main.mdx.

Limites d'usage

Pas de clé, donc pas de quota à déclarer. Une limite souple d'environ 60 requêtes par minute et par IP est appliquée par le CDN ; au-delà, la réponse est un 429 avec le code rate_limited. Rien dans l'API publique n'écrit quoi que ce soit : un nouvel essai est toujours sans risque.

Ce que l'API ne fait pas

Générer un visuel ne fait pas partie de l'API publique. Cela demande un compte connecté, la bibliothèque d'images de l'utilisateur et ses crédits : tout cela vit dans le studio, sur kreafy.ai/login. Si vous construisez un agent, envoyez-y l'utilisateur plutôt que d'essayer d'automatiser le studio.