Parcourir la documentation

L'API publique

Lire et écrire dans un atelier depuis un script, avec une clé d'API — l'adresse, les erreurs, les limites, les opérations.

L'API publique fait depuis un programme ce que l'application fait à l'écran : écrire un article, le publier, ajouter une image, lire les statistiques. Elle est ouverte à toutes les offres.

L'adresse et la clé

Adresse: https://api.typoza.com/v1
Clé: À créer dans Réglages → Intégrations — voir Les clés d'API
En-tête: Authorization: Bearer typ_live_…
Description OpenAPI: https://api.typoza.com/v1/openapi.json, ouverte sans clé

Une clé ouvre un atelier, celui où elle a été créée, au nom de la personne qui l'a créée. Elle agit avec le rôle qu'on lui a donné, jamais au-delà de celui de cette personne.

curl https://api.typoza.com/v1/me \
  -H "Authorization: Bearer typ_live_…"

/v1/me ne change rien : c'est la façon la plus sûre de vérifier une clé.

Les opérations

GET /me: L'atelier, la personne et la clé
GET /posts: Les articles, filtrés par statut, catégorie, mot-clé ou titre
GET /posts/{id}: Un article, corps compris
POST /posts: Un article neuf, toujours en brouillon
PATCH /posts/{id}: Changer un article : ce qui est envoyé change, le reste reste
POST /posts/{id}/submit: Le soumettre à la relecture
POST /posts/{id}/publish: Le publier, tout de suite ou à une date (publishAt)
POST /posts/{id}/unpublish: Le remettre en brouillon
GET /media: La médiathèque
POST /media: Ajouter une image : jointe (multipart/form-data, champ file) ou par son adresse (url)
GET /stats: Les statistiques d'une période — 7d, 30d, 12m ou all, selon ce que garde l'offre
GET /categories · POST · PATCH /categories/{id}: Les catégories
GET /tags · POST /tags: Les mots-clés
GET /pages · GET /pages/{id} · POST · PATCH: Les pages
POST /pages/{id}/publish · /unpublish: Publier ou retirer une page

Chaque opération demande le rôle qu'elle demande à l'écran. Un auteur écrit et publie ses propres articles ; un relecteur lit la file de relecture ; créer une catégorie ou un mot-clé, et toucher aux pages, demande un éditeur. Voir Les rôles.

Rien ne se supprime par l'API — ni article, ni page, ni image —, et la Lettre n'y est pas : ses envois et ses abonnés restent à l'écran.

Le corps d'un article

À l'envoi, body est du Markdown, ou le document lui-même :

{ "title": "Notes de voyage", "body": "## Lisbonne\n\nTrois jours de pluie." }

Un # devient un intertitre ## — l'article a déjà son titre. Une image s'écrit seule sur sa ligne — ![Texte alternatif](https://…) —, et son adresse doit venir de la médiathèque de l'atelier : ajoutez d'abord l'image par POST /media, puis reprenez l'url qu'il rend. Une image venue d'ailleurs est refusée plutôt qu'effacée en silence.

À la lecture, ?format=markdown (par défaut), json ou html. Le Markdown rendu se renvoie tel quel : ce que l'API écrit, elle le relit.

Un corps ne se remplace pas pendant qu'un fil de relecture est ouvert sur un passage de l'article : l'API répond review_in_progress. Le titre et le reste se changent quand même.

Pour publier à une date, publishAt porte son fuseau — 2026-10-01T09:00:00+02:00 — et doit être dans le futur. Sans fuseau, la date est refusée plutôt que lue à l'heure du serveur.

Les listes

Les listes se lisent page par page : limit (de 1 à 100, 20 par défaut), puis cursor pour la suite.

{ "data": [ … ], "hasMore": true, "nextCursor": "MjAyNi0wOS0yOVQxMDowMDowMC4wMDBafGNt…" }

Un article publié entre deux appels ne décale rien : la page suivante reprend après la dernière ligne vue.

Les erreurs

Toutes ont la même forme, et requestId est ce qu'il faut citer en nous écrivant :

{
  "error": {
    "type": "conflict",
    "code": "slug_taken",
    "message": "Another post in this workspace already uses this slug.",
    "param": "slug",
    "requestId": "req_7f3a…"
  }
}

400: La demande est mal formée — param nomme le champ
401: Pas de clé, ou une clé qui ne vaut plus : révoquée, échue, inconnue, ou dont l'auteur a perdu le rôle
403: Le rôle de la clé ne le permet pas, ou l'atelier est en lecture seule
404: Rien ici — ou rien que cette clé ait le droit de voir
409: Un conflit : un slug pris, une relecture en cours
429: Trop de requêtes : réessayer après Retry-After secondes

Les messages sont en anglais, comme les codes : ce sont eux qu'un script lit.

Les limites

Par adresse IP: 600 requêtes par minute
Par clé: 120 requêtes par minute, dont 30 écritures
Téléversements: 20 images par minute et par personne, écran compris
Taille d'une image: 4 Mo — voir Les formats acceptés

Les mêmes pour toutes les offres.

Rejouer une écriture sans la doubler

Une création perdue dans une coupure réseau peut se renvoyer sans créer deux brouillons : ajoutez un en-tête Idempotency-Key, une valeur à vous, neuve pour chaque écriture.

curl https://api.typoza.com/v1/posts \
  -H "Authorization: Bearer typ_live_…" \
  -H "Idempotency-Key: import-2026-09-29-001" \
  -H "Content-Type: application/json" \
  -d '{"title": "Notes de voyage"}'

La même requête sous la même clé, pendant 24 heures, rend la même réponse, avec l'en-tête Idempotent-Replayed: true. Une autre requête sous la même clé est refusée (idempotency_key_reused).

Ce qui reste visible

Chaque écriture entre au journal d'activité de l'atelier, au nom de la personne et avec le nom de la clé. Voir Le journal d'activité.

Pour un assistant d'IA plutôt qu'un script, la même clé se branche sur notre serveur MCP : Brancher un assistant d'IA.