Une API REST en JSON, à l’adresse https://api.memojin.com/v1. Ces règles valent pour toutes les opérations ; la référence de chaque ressource les rappelle au besoin.
Format des requêtes et des réponses
- JSON seulement : envoyez
Content-Type: application/jsonavec un corps (sinon415 unsupported_media_type) et acceptezapplication/json(sinon406 not_acceptable). Un corps ne dépasse pas 1 Mo (413 payload_too_large). - Champs en
camelCase; identifiants en UUID ; instants en ISO 8601 UTC (2026-10-01T14:03:00.000Z). Une valeur absente vautnull, une liste vide[]: les champs d’un objet sont toujours présents. - Une ressource est rendue telle quelle ; une liste, sous la forme
{ "data": [...], "nextCursor": "…", "hasMore": true }. - Les URL d’image (
imageUrl) sont signées et de courte durée : téléchargez l’image si vous en avez besoin, ne conservez pas l’URL.
Statuts de succès
| Statut | Quand | Corps |
|---|---|---|
200 OK | Lecture, modification | L’objet, ou une page |
201 Created | Création | L’objet créé, et l’en-tête Location |
202 Accepted | Génération IA lancée | Le travail à suivre (jobId) |
204 No Content | Suppression | Aucun |
304 Not Modified | If-None-Match qui correspond | Aucun |
Soyez tolérant
De nouveaux champs, de nouvelles valeurs d’énumération (un statut, un type de travail) et de nouveaux codes d’erreur peuvent apparaître sans préavis dans /v1. Ignorez les champs que vous ne connaissez pas et traitez une valeur inconnue comme un cas générique. Voir versions.
En-têtes
| En-tête | Sens | Rôle |
|---|---|---|
Authorization | requête | Bearer mj_live_… ou mj_test_… (authentification) |
Idempotency-Key | requête | Un UUID par opération POST, réutilisé à chaque nouvelle tentative (idempotence) |
If-None-Match | requête | L’ETag détenu : 304 si rien n’a changé (requêtes conditionnelles) |
If-Match | requête | L’ETag lu : 412 sur PATCH ou DELETE si la ressource a changé depuis |
Accept-Language | requête | Langue des messages d’erreur : en (défaut), fr, es, de, it |
X-Request-Id | les deux | Votre identifiant, renvoyé tel quel (généré sinon) ; citez-le si vous nous contactez |
ETag | réponse | Version de la représentation rendue par un GET |
Cache-Control | réponse | private, no-cache sur les lectures (revalidez avec If-None-Match) |
Location | réponse | Chemin de la ressource créée par un 201 |
Link | réponse | rel="next" (page suivante), rel="help" (documentation d’un code d’erreur), rel="deprecation" |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset | réponse | Votre fenêtre de limite en cours (limites) |
Retry-After | réponse | Secondes à attendre, sur 429, 503 et 409 idempotency_in_progress |
Idempotent-Replayed | réponse | true quand la réponse rejoue une réponse antérieure |
Memojin-Version | réponse | Version du contrat qui a servi la requête (versions) |
Memojin-Credits-Estimate | réponse | Unités de crédit IA qu’une génération prévoit (ai_card=12) |
Deprecation, Sunset | réponse | Posés sur une opération dont le retrait est programmé (RFC 9745, RFC 8594) |