Vue d'ensemble API

Conventions partagées par tous les endpoints de l'API Outsend — URL de base, authentification, types de contenu, versioning, erreurs.

Vue d'ensemble API

L'API Outsend expose la même surface que l'application web. Le tableau de bord et l'API partagent un backend, un schéma d'authentification et un ensemble d'objets uniques.

URL de base

https://outsend.xyz

Les endpoints sous /api/ renvoient du JSON ou diffusent des événements. L'URL de base est stable durant l'alpha.

Authentification

Les sessions utilisent un cookie nommé outsend_session. Pour l'obtenir, envoyer les identifiants :

POST /api/auth/login
Content-Type: application/json

{ "email": "nom@example.com", "password": "..." }

La réponse pose outsend_session en HttpOnly, Secure, SameSite=Lax. Les requêtes suivantes doivent l'inclure. Les sessions restent valides jusqu'à la déconnexion (POST /api/auth/logout) ou expiration. Les requêtes sans cookie valide reçoivent 401 sur les routes protégées.

Des jetons API scopés par workspace sont prévus à la feuille de route ; les sessions par cookie sont actuellement le seul mécanisme supporté.

Types de contenu

Les endpoints acceptant format retournent du JSON par défaut.

Versioning

L'API est en alpha. Aucun préfixe /v1/, aucun header de version — la surface évolue sur place. Les ruptures sont annoncées à l'avance via le changelog et, le cas échéant, par bannières in-app. Les ajouts (nouveaux champs, endpoints, paramètres optionnels) sont livrés sans préavis. Un préfixe versionné sera introduit avant la disponibilité générale.

Limites de débit

Les endpoints sensibles (authentification, contact, création de jobs) sont protégés par des quotas par route. Le dépassement renvoie 429 avec un en-tête Retry-After. Voir /docs/fr/concepts/limits.

Erreurs

Les échecs renvoient un corps JSON et un code HTTP conventionnel :

{
  "detail": "Message lisible",
  "errors": [
    { "field": "email", "message": "Format invalide" }
  ]
}

Le tableau errors n'est présent que lorsque l'échec concerne des champs spécifiques.

Considérer tout 5xx comme transitoire et appliquer un backoff exponentiel.

Groupes d'endpoints

Protocole SSE

Les opérations longues exposent leur progression via Server-Sent Events. Noms d'événements, forme de payload et machine à états sont documentés sur /docs/fr/concepts/states-and-events.