Public API StormeoOS — /api/public/v1

API REST pour intégrateurs externes (Zapier, n8n, applications maison, scripts d'agence). Authentifiée par clé API spk_* envoyée dans le header x-api-key.

Base URL

Environnement	URL
Production	https://beta.stormeo.io/api/public/v1
Développement local	http://localhost:3000/api/public/v1

Quick start

# 1. Vérifier que la clé fonctionne (renvoie usage actuel)
curl -H "x-api-key: spk_votre_clef_48_hex" \
  https://beta.stormeo.io/api/public/v1/me

# 2. Lister les clients de votre agence
curl -H "x-api-key: spk_votre_clef_48_hex" \
  "https://beta.stormeo.io/api/public/v1/clients?limit=20&offset=0"

# 3. Créer un client
curl -X POST \
  -H "x-api-key: spk_votre_clef_48_hex" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme SARL","email":"contact@acme.fr"}' \
  https://beta.stormeo.io/api/public/v1/clients

Sommaire

Document	Contenu
authentication.md	Génération, scopes, IP whitelist, expiration, révocation
rate-limiting.md	Limites par minute / jour, headers X-RateLimit-*, code 429
errors.md	Format des réponses d'erreur, codes énumérés, retry
conventions.md	REST patterns, pagination, dates, encodage JSON
changelog.md	Versions de l'API publique
endpoints/	Référence par domaine (CRM, facturation, tickets, etc.)
examples/	Snippets curl + collection Postman

Endpoints par domaine

Domaine	Documentation	Scopes
Meta (/me, /scopes, /health)	endpoints/meta.md	(aucun)
CRM — Clients	endpoints/clients.md	clients:read, clients:write, clients:delete
CRM — Contacts	endpoints/contacts.md	contacts:read, contacts:write, contacts:delete
CRM — Sites web	endpoints/websites.md	websites:read, websites:write, websites:delete
Ticketing	endpoints/tickets.md	tickets:read, tickets:write, tickets:delete
Facturation — Factures	endpoints/invoices.md	invoices:read, invoices:write
Facturation — Devis	endpoints/quotes.md	quotes:read, quotes:write
Planning — Tâches	endpoints/tasks.md	tasks:read, tasks:write, tasks:delete
Planning — Événements	endpoints/events.md	events:read, events:write, events:delete
Veille	endpoints/watches.md	watches:read, watches:write
Webhooks (gestion)	endpoints/webhooks.md	webhooks:manage

Pour les notifications push (webhooks émis vers votre URL), voir ../webhooks/public-api-webhooks.md.

Pré-requis

• Plan d'agence avec api_access activé. Sans ce flag, toute requête est rejetée en 403 PLAN_UPGRADE_REQUIRED.
• Clé API générée depuis Compte > Intégrations > API publique (ou POST /api/public-api/admin/keys côté admin).
• Scopes appropriés sur la clé (CRUD par ressource, voir authentication.md).

Multi-tenant et isolation

Chaque clé API est rattachée à une agence (agencyId). Toutes les requêtes sont automatiquement filtrées par cet agencyId côté serveur. Vous ne pouvez pas accéder aux données d'une autre agence, même si vous connaissez un ID.

Format de réponse

Succès liste :

{
  "data": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Succès création / lecture / mise à jour : la ressource directement.

{ "id": 42, "name": "Acme SARL", "createdAt": "2026-04-27T10:00:00.000Z" }

Suppression : 204 No Content.

Erreur : voir errors.md.