Automatiser vos annonces avec l’API

L’API pealHQ permet à vos automatisations (pipeline de release, n8n, Zapier, script) de lire les demandes de votre portail, de rédiger l’annonce d’une version et de la publier. Une relance de la même automatisation met à jour l’annonce existante au lieu d’en créer une seconde.

Ce guide peut être partagé avec votre équipe technique ou un agent de développement. Les valeurs des exemples sont fictives.

Créer une clé API

1. Ouvrez Paramètres → API dans l’administration pealHQ.
2. Donnez un nom à la clé (par exemple « Release GitHub Actions »), puis cliquez sur Créer.
3. Copiez la clé affichée, qui commence par peal_. Elle n’est affichée qu’une fois : pealHQ n’en conserve qu’une empreinte.
4. Enregistrez-la dans les secrets de votre automatisation, jamais dans le code.

Une clé donne accès à un seul workspace et agit au nom du membre de l’équipe qui l’a créée : les annonces créées par l’API lui sont attribuées. Elle cesse de fonctionner dès que ce membre quitte l’équipe. Révoquez une clé depuis la même page ; l’effet est immédiat.

Appeler l’API

Toutes les URL partent de l’adresse affichée dans Paramètres → API, par exemple :

https://pealhq.com/api/v1

Chaque appel envoie la clé dans l’en-tête Authorization. Les corps de requête et de réponse sont en JSON :

curl https://pealhq.com/api/v1/changelog \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json"

Chaque réponse place la ressource dans une clé data. L’API accepte 120 appels par minute et par clé.

Codes d’erreur

Lire une demande

GET /requests/{id}

L’identifiant est celui de l’URL d’administration de la demande, …/admin/requests/{id}. C’est aussi le lien que pealHQ ajoute aux issues Linear créées ou liées depuis le triage : votre automatisation peut le lire dans les pièces jointes de l’issue.

{
  "data": {
    "id": 42,
    "title": "Exporter les factures en CSV",
    "description": "Nous aimerions exporter toutes les factures du mois…",
    "status": "completed",
    "status_label": "Livrée",
    "votes_count": 18,
    "comments_count": 4,
    "created_at": "2026-09-02T08:15:00.000000Z",
    "archived_at": null,
    "merged_into_id": null,
    "linear_issue": {
      "identifier": "ACME-123",
      "url": "https://linear.app/acme/issue/ACME-123"
    },
    "changelog": null,
    "public_url": "https://acme.pealhq.com/requests/42",
    "admin_url": "https://acme.pealhq.com/admin/requests/42"
  }
}

changelog indique l’annonce à laquelle la demande est déjà rattachée (id, version, status, public_url), ou null.

Créer ou mettre à jour une version

PUT /changelog/versions/{version}

La version identifie l’annonce : 2.4.0, v2.4.0-beta.1 ou 2026.10.08 (lettres, chiffres, ., _, + et -, 50 caractères au plus). Si aucune annonce n’existe pour cette version, elle est créée en brouillon et la réponse a le code 201. Sinon, son contenu est remplacé et la réponse a le code 200.

curl -X PUT https://pealhq.com/api/v1/changelog/versions/2.4.0 \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Version 2.4 : exports CSV",
    "body": "## Exports CSV\n\nExportez toutes vos factures du mois en un clic.",
    "feature_request_ids": [42, 57]
  }'

{
  "data": {
    "id": 318,
    "version": "2.4.0",
    "status": "draft",
    "title": "Version 2.4 : exports CSV",
    "summary": "Exportez toutes vos factures du mois en un clic.",
    "body": "## Exports CSV\n\nExportez toutes vos factures du mois en un clic.",
    "cover_url": null,
    "auto_open_widget": false,
    "published_at": null,
    "scheduled_for": null,
    "created_at": "2026-10-08T09:30:00.000000Z",
    "updated_at": "2026-10-08T09:30:00.000000Z",
    "public_url": "https://acme.pealhq.com/changelog#entry-318",
    "admin_url": "https://acme.pealhq.com/admin/changelog",
    "feature_requests": [
      { "id": 42, "title": "Exporter les factures en CSV" },
      { "id": 57, "title": "Filtrer les exports par client" }
    ]
  }
}

public_url est l’adresse de l’annonce sur votre portail. Elle n’est visible par vos clients qu’après publication.

Une demande ne peut être annoncée que dans une seule annonce. Lorsqu’une demande passe au statut livré, pealHQ l’ajoute au brouillon automatique du jour (« Nouveautés du … »). En la liant à votre version, l’API la retire de ce brouillon, avec la section qui avait été générée pour elle ; le brouillon est supprimé s’il ne contient plus rien. Une section modifiée à la main est conservée. Une demande déjà présente dans une autre annonce publiée est refusée avec le code 422.

Retrouver une annonce

GET /changelog/versions/{version}
GET /changelog/{id}

Renvoient l’annonce au même format, ou 404 si elle n’existe pas.

GET /changelog?status=draft

Liste les annonces, des plus récentes aux plus anciennes, 25 par page (per_page, jusqu’à 100). Le filtre facultatif status vaut draft, scheduled ou published. La réponse contient data, links et meta, pour suivre la pagination avec links.next.

Modifier un brouillon

PATCH /changelog/{id}

Ne modifie que les champs envoyés : title, summary, body, version, feature_request_ids et auto_open_widget, avec les mêmes règles que ci-dessus. Utilisez-le notamment pour réécrire un brouillon automatique ou lui attribuer une version.

curl -X PATCH https://pealhq.com/api/v1/changelog/318 \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Les exports CSV arrivent dans la facturation."}'

Une annonce publiée ne peut plus être modifiée par l’API : toute modification renvoie 409. Rejouer exactement le même contenu reste accepté et ne change rien, ce qui permet de relancer une automatisation déjà terminée. Pour corriger une annonce publiée, repassez-la en brouillon depuis l’administration.

Publier une annonce

POST /changelog/{id}/publish

Publie immédiatement l’annonce sur le portail, dans le widget, et prévient vos clients selon leurs préférences de notification. Une publication programmée depuis l’administration est annulée. Publier une annonce déjà publiée ne change rien, pas même sa date.

curl -X POST https://pealhq.com/api/v1/changelog/318/publish \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json"

Exemple de workflow de release

1. Votre pipeline rassemble les issues Linear de la release et lit, dans leurs pièces jointes, les liens …/admin/requests/{id} ajoutés par pealHQ.
2. Pour chaque identifiant, GET /requests/{id} fournit le titre, la description et le nombre de votes, utiles pour rédiger l’annonce.
3. PUT /changelog/versions/{version} crée ou met à jour le brouillon avec le titre, le contenu Markdown et les identifiants des demandes.
4. Selon votre processus, un membre de l’équipe relit le brouillon dans l’administration, ou le pipeline appelle POST /changelog/{id}/publish.
5. Le pipeline partage public_url dans ses notes de version ou sur Slack.

En cas d’échec, relancez le pipeline tel quel : les étapes 3 et 4 ne créent jamais de doublon.

#!/usr/bin/env bash
set -euo pipefail

API="https://pealhq.com/api/v1"
VERSION="2.4.0"

entry=$(curl -sf -X PUT "$API/changelog/versions/$VERSION" \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @release-notes.json)

id=$(echo "$entry" | jq -r '.data.id')

curl -sf -X POST "$API/changelog/$id/publish" \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" | jq -r '.data.public_url'