← Residual PublishCommencer →

Documentation

API Reference

Toutes les routes REST de Residual Publish. Authentification via JWT Supabase (header Authorization: Bearer <token>).

Base URL — https://publish.residual-labs.fr
Toutes les routes nécessitent un token JWT valide sauf /api/v1/webhook/typebot (webhook public signé).

Démarrage rapideArticlesConnexions (BYOK)WebhooksScheduling

Démarrage rapide

POST/api/v1/generate

Générer un article

Génère un article complet via streaming SSE. Utilise Mistral large (ou Groq en fallback) avec vos données d'audit comme contexte.

Paramètre
Type
Req.
Description
topic
string
✓
Sujet ou secteur ciblé (ex: "restaurants Paris")
tone
number
—
Ton de l'article : 0 = neutre, 100 = provocation (défaut: 50)
audit_data
object
—
Données brutes Residual Audit (scores, failles, CVW)
model
string
—
"mistral" | "groq" (défaut: mistral avec fallback groq)
POST /api/v1/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "topic": "agences SEO Paris 2026",
  "tone": 70,
  "audit_data": {
    "sector": "agences-seo",
    "sample_size": 50,
    "avg_score": 62,
    "critical_issues": ["LCP > 4s", "missing canonical", "no HTTPS"]
  }
}
POST/api/v1/publish

Publier un article

Publie un article existant sur la plateforme choisie. La connexion doit être configurée dans /connections.

Paramètre
Type
Req.
Description
article_id
string (UUID)
✓
ID de l'article à publier
platform
string
✓
"wordpress" | "twitter" | "linkedin"
connection_id
string (UUID)
—
ID de connexion (défaut: première connexion active)
POST /api/v1/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "article_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "wordpress",
  "connection_id": "550e8400-e29b-41d4-a716-446655440001"
}

Articles

GET/api/v1/articles

Lister les articles

Retourne tous les articles de l'utilisateur authentifié, triés par date de création.

Paramètre
Type
Req.
Description
status
query
—
Filtrer par statut : "draft" | "published" | "scheduled"
limit
query
—
Nombre max de résultats (défaut: 20, max: 100)
GET /api/v1/articles?status=published&limit=10
Authorization: Bearer <token>
GET · PATCH · DELETE/api/v1/articles/:id

Récupérer / modifier / supprimer un article

Opérations CRUD sur un article. L'IDOR est vérifié — seul le propriétaire peut modifier.

Paramètre
Type
Req.
Description
title
string
—
(PATCH) Nouveau titre
body
string
—
(PATCH) Contenu HTML ou Markdown
status
string
—
(PATCH) Changer le statut
PATCH /api/v1/articles/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Nouveau titre optimisé",
  "status": "published"
}

Connexions (BYOK)

GET · POST · DELETE/api/v1/connections

Gérer les connexions

Gère les connexions aux plateformes (WordPress, Twitter, Mistral, Groq). Les credentials sont chiffrés AES-256-GCM avant stockage.

Paramètre
Type
Req.
Description
provider
string
✓
"wordpress" | "twitter" | "linkedin" | "mistral" | "groq"
label
string
✓
Nom affiché dans l'interface
credentials
object
✓
Dépend du provider (voir exemples)
POST /api/v1/connections
Authorization: Bearer <token>
Content-Type: application/json

// WordPress
{
  "provider": "wordpress",
  "label": "Mon Blog",
  "credentials": {
    "url": "https://monblog.fr",
    "username": "admin",
    "password": "xxxx xxxx xxxx xxxx xxxx xxxx"
  }
}

// Mistral BYOK
{
  "provider": "mistral",
  "label": "Ma clé Mistral",
  "credentials": { "api_key": "sk-..." }
}

Webhooks

POST/api/v1/webhook/typebot

Webhook Typebot

Reçoit les leads capturés par votre chatbot Typebot embarqué dans les articles WordPress. Score le lead via GoRules et l'envoie vers Residual Reach.

Paramètre
Type
Req.
Description
email
string
✓
Email du prospect
name
string
—
Prénom / Nom
company
string
—
Entreprise
source_url
string
—
URL de l'article source
answers
object
—
Réponses du bot (score contextuel)
POST /api/v1/webhook/typebot
Content-Type: application/json
X-Article-Id: 550e8400-e29b-41d4-a716-446655440000

{
  "email": "contact@agence.fr",
  "name": "Marie Dupont",
  "company": "Agence XYZ",
  "source_url": "https://monblog.fr/article-seo-paris",
  "answers": { "budget": "5k-10k", "timeline": "Q3 2026" }
}

Scheduling

POST/api/v1/schedule

Programmer une publication

Programme la publication d'un article à une date et heure précises. Le cron Trigger.dev exécute la publication automatiquement.

Paramètre
Type
Req.
Description
article_id
string (UUID)
✓
Article à programmer
platform
string
✓
Plateforme cible
scheduled_at
ISO 8601
✓
Date et heure de publication
connection_id
string (UUID)
—
Connexion à utiliser
POST /api/v1/schedule
Authorization: Bearer <token>
Content-Type: application/json

{
  "article_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "wordpress",
  "scheduled_at": "2026-06-15T09:00:00Z"
}

MCP Server (Claude Code)

Residual Publish expose un MCP Server compatible Claude Code avec 4 outils. Configurez-le dans votre .mcp.json :

{
  "mcpServers": {
    "residual-publish": {
      "url": "https://publish.residual-labs.fr/api/v1/mcp",
      "headers": { "Authorization": "Bearer <votre-token>" }
    }
  }
}

// Outils disponibles :
// generate_article(topic, tone?, audit_data?)
// publish_article(article_id, platform, connection_id?)
// schedule_article(article_id, platform, scheduled_at)
// article_stats(article_id)
Residual PublishBlogChangelogÀ propos