Référence complète des endpoints

Spécification OpenAPI 3.1 de l'API publique Diamond Careers, paramètres, corps de requête et schémas de réponse.

L'intégralité de l'API publique est décrite dans une spécification OpenAPI 3.1 maintenue à jour avec l'évolution de la plateforme.

Consulter la spécification

Fichier source : /openapi.yaml.

Visualiser interactivement

Swagger UI ou Redoc pour une visualisation web,
Postman, Insomnia ou Bruno pour l'explorer et tester les requêtes,
Stoplight Studio pour la documentation enrichie.

Chacun accepte le fichier openapi.yaml directement.

Générer un client typé

OpenAPI Generator (openapi-generator.tech) — 50+ langages.
Orval (orval.dev) — TypeScript / React Query / SWR.
Heyapi (heyapi.dev) — TypeScript moderne.
autorest (github.com/Azure/autorest) — .NET / Python / TypeScript.

Exemple TypeScript :

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./diamond-client

Intégrer dans votre documentation interne

Le fichier openapi.yaml est réutilisable librement par vos équipes. Pensez à le re-télécharger régulièrement pour rester aligné sur les évolutions.

Couverture

La spécification couvre les ressources accessibles à un compte établissement ou groupe :

Authentification (/auth/login, /auth/me, /auth/logout),
Établissement (/maisons/{id}),
Offres (/offres, /offres/{id}),
Candidatures (/candidatures, /candidatures/{id}/status),
Articles (/articles),
Équipe (/etablissement/members, /etablissement/members/{user_id}),
Médias (/upload, /secure-upload, /secure-file),
Taxonomies de référence (/taxonomies/{name}),
Groupe (/groupes/{id}/maisons, /offres, /candidatures, /stats).

Les endpoints internes (validation, modération, communication globale, supervision) ne sont pas exposés dans la spécification publique : ils sont strictement réservés à l'équipe Diamond Careers.

Conventions

Les comportements transverses sont décrits dans :

Vue d'ensemble — base URL, format JSON,
Authentification — jeton Bearer,
Pagination, filtres et tri — per_page, page, s, filter[*], tax[*], orderby, order, status,
Codes d'erreur — structure des réponses 4xx et 5xx,
Rate limits — limites de débit et en-têtes associés.

Reportez-vous à ces guides en complément de la spécification.

L'API est exposée sous la version v1. Toute évolution incompatible (suppression d'un champ, changement de type, retrait d'un endpoint) déclenche la création d'une nouvelle version v2 plutôt que la modification de la version courante. La v1 reste alors maintenue en parallèle pendant une période minimale d'un an pour vous laisser le temps de migrer.

Les évolutions compatibles (ajout de champ optionnel, ajout d'endpoint, ajout de valeur d'enum) sont publiées directement sur v1 sans changement de version.

Pour le changelog, écrivez à tech@diamondcareers.fr avec en objet « Inscription changelog API ».