Conventions de l’API

Format, pagination, erreurs, idempotence, limites de débit et versions.

Toutes les ressources de l'API suivent les mêmes règles : apprenez-les une fois, elles valent pour chaque endpoint.

URL de base et format

URL de base https://strikespace.net/api/platform/v1
Transport HTTPS uniquement. Corps de requête et de réponse en JSON UTF-8 (Content-Type: application/json).
Nommage Champs en snake_case. Chaque objet porte "object": "<type>" et un id (UUID).
Dates ISO 8601 en UTC, par exemple 2026-10-16T10:05:51.000Z. En entrée, toute date ISO 8601 avec fuseau est acceptée.
Montants Entiers dans l'unité de la devise (FCFA : 15000 = 15 000 FCFA), avec currency.
Valeurs absentes Les champs sans valeur sont présents avec null, jamais omis.
Cache Les réponses portent Cache-Control: no-store.

Pagination

Les endpoints de liste retournent une enveloppe commune, triée du plus récent au plus ancien :

JSON
{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "8f14e45f-ceea-4e7a-9a3b-2c1d5e6f7a80",
      "first_name": "Awa"
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0xNFQwOToxMjozMS4wMDBafDhmMTRlNDVm"
}
  • limit : de 1 à 100 éléments par page, 25 par défaut.
  • cursor : passez la valeur next_cursor reçue pour obtenir la page suivante. Le curseur est opaque : ne le construisez pas et ne l'interprétez pas.
  • La pagination par curseur est stable : un élément créé pendant que vous parcourez la liste ne décale pas les pages suivantes.
  • Les filtres doivent être identiques d'une page à l'autre.
// Parcourt toutes les pages de /leads
async function* allLeads() {
  let cursor = null
  do {
    const url = new URL('https://strikespace.net/api/platform/v1/leads')
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.STRIKE_API_KEY}` },
    })
    const page = await response.json()
    if (!response.ok) throw new Error(page.error.message)
    yield* page.data
    cursor = page.has_more ? page.next_cursor : null
  } while (cursor)
}

for await (const lead of allLeads()) console.log(lead.id)
import os
import requests

def all_leads():
    params = {"limit": 100}
    headers = {"Authorization": f"Bearer {os.environ['STRIKE_API_KEY']}"}
    while True:
        response = requests.get("https://strikespace.net/api/platform/v1/leads", headers=headers, params=params, timeout=10)
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if not page["has_more"]:
            break
        params["cursor"] = page["next_cursor"]

for lead in all_leads():
    print(lead["id"])

Erreurs

Toute erreur renvoie un code HTTP adapté et le même format JSON :

Réponse 403
{
  "error": {
    "type": "permission_error",
    "message": "Cette clé n’a pas la permission « Créer, modifier et supprimer des leads » (scope leads:write).",
    "code": "insufficient_scope",
    "request_id": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
  }
}
HTTP type Signification et conduite à tenir
400 / 422 invalid_request Requête mal formée ou champ invalide ; param désigne le champ. Corrigez avant de renvoyer.
401 authentication_error Clé ou jeton absent, invalide, expiré ou révoqué. L'en-tête WWW-Authenticate indique les métadonnées OAuth.
403 permission_error Accès refusé. code précise : insufficient_scope, plan_required, ip_not_allowed, ou une règle métier (quota, canal non inclus).
404 not_found Ressource inexistante ou appartenant à un autre compte.
409 conflict Conflit d'état : version obsolète, doublon, Idempotency-Key réutilisée avec un autre corps, limite de l'offre atteinte.
429 rate_limit Trop de requêtes (code: "rate_limited"). Attendez Retry-After secondes.
500 internal Erreur de notre côté. Réessayez avec un délai croissant ; si elle persiste, contactez-nous avec le request_id.
Réponse 422
{
  "error": {
    "type": "invalid_request",
    "message": "Le champ email doit être une adresse email valide.",
    "param": "email",
    "request_id": "0b7e2c4a-1d3f-4e5a-9b6c-7d8e9f0a1b2c"
  }
}

Les messages (message) sont rédigés en français pour être affichés ou journalisés ; basez votre logique sur type et code, qui sont stables.

Identifiant de requête

Chaque réponse, succès ou erreur, porte un en-tête X-Request-Id (repris dans error.request_id). Journalisez-le : il permet à notre support de retrouver votre appel dans nos journaux, et il apparaît dans votre Journal développeurs.

Idempotence

Les requêtes POST acceptent un en-tête Idempotency-Key (255 caractères maximum, par exemple un UUID v4 ou votre identifiant métier). Pendant 24 heures :

  • la même clé avec le même corps rejoue la réponse enregistrée, sans refaire l'opération, avec l'en-tête Idempotent-Replayed: true ;
  • la même clé avec un corps différent est refusée : 409, code: "idempotency_key_reused" ;
  • la même clé pendant que la première requête est encore en cours : 409, code: "idempotency_request_in_progress" (réessayez un instant plus tard) ;
  • une réponse d'erreur n'est pas mémorisée : après correction, un nouvel envoi avec la même clé est exécuté normalement.
curl
# Le même appel peut être rejoué sans risque pendant 24 h
curl -X POST 'https://strikespace.net/api/platform/v1/leads' \
  -H "Authorization: Bearer $STRIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-contact-48213" \
  -d '{ "first_name": "Awa", "email": "awa@exemple.com" }'

# Second envoi identique : réponse stockée, en-tête « Idempotent-Replayed: true »

Utilisez-la systématiquement pour les créations (leads, événements, publications, inscriptions) : en cas de coupure réseau ou de délai dépassé, vous pouvez renvoyer sans risque de doublon. PATCH et DELETE sont naturellement idempotents.

Limites de débit

Les limites protègent la plateforme et dépendent de votre offre. La limite par minute s'applique à chaque clé ou agent connecté ; la limite journalière à l'ensemble du compte.

Limite Pro Enterprise
Requêtes par minute, par clé ou agent 60 300
Requêtes par jour, par compte 50 000 500 000
Clés API actives 10 50
Endpoints de webhooks 5 25
Agents IA connectés 20 100

Chaque réponse indique votre consommation de la minute en cours :

HTTP
HTTP/1.1 200 OK
X-Request-Id: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 42

HTTP/1.1 429 Too Many Requests
Retry-After: 18
RateLimit-Remaining: 0
RateLimit-Reset: 18
  • RateLimit-Limit : requêtes autorisées par minute ;
  • RateLimit-Remaining : requêtes restantes ;
  • RateLimit-Reset : secondes avant la remise à zéro ;
  • en cas de dépassement : 429 et Retry-After (secondes).

Renvoyez uniquement les 429 et les 5xx, avec un délai croissant et un peu d'aléa :

// Renvoi avec délai croissant sur 429 et 5xx uniquement
async function strikeFetch(url, options = {}, attempt = 0) {
  const response = await fetch(url, options)
  const retryable = response.status === 429 || response.status >= 500
  if (!retryable || attempt >= 4) return response
  const retryAfter = Number(response.headers.get('retry-after'))
  const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** attempt)
  await new Promise((resolve) => setTimeout(resolve, delay + Math.random() * 250))
  return strikeFetch(url, options, attempt + 1)
}
import random
import time
import requests

def strike_request(method, url, attempt=0, **kwargs):
    response = requests.request(method, url, timeout=10, **kwargs)
    retryable = response.status_code == 429 or response.status_code >= 500
    if not retryable or attempt >= 4:
        return response
    retry_after = response.headers.get("Retry-After")
    delay = int(retry_after) if retry_after and retry_after.isdigit() else min(30, 0.5 * 2 ** attempt)
    time.sleep(delay + random.random() / 4)
    return strike_request(method, url, attempt + 1, **kwargs)

Versions

La version actuelle de l'API est 2026-10-01. Elle figure dans le chemin (/v1) et dans le champ api_version de chaque événement webhook.

  • Changements compatibles, sans préavis : nouveaux endpoints, nouveaux champs dans les réponses, nouveaux paramètres facultatifs, nouveaux types d'événements, nouvelles valeurs de code. Votre code doit ignorer les champs inconnus.
  • Changements incompatibles (suppression ou renommage d'un champ, changement de type) : publiés dans une nouvelle version datée, annoncés à l'avance dans le changelog et par email ; l'ancienne version reste disponible pendant une période de transition.

Une question sur l'intégration ? Écrivez à contact@strike.app en indiquant l'endpoint, l'heure et le request_id de la réponse.