API Griot

Publiez sur les réseaux de votre espace depuis vos propres applications, avec une simple clé API.

URL de base: https://api.griot.social/v1

Authentification

Chaque requête porte l’en-tête Authorization avec une clé de votre espace. Créez-la dans Espace › Clés API : elle n’est affichée qu’une seule fois. Clés API

export GRIOT_API="https://api.griot.social/v1"
export GRIOT_KEY="grt_live_…"        # votre clé API
export WS="…"                        # identifiant de votre espace

1. Lister vos comptes connectés

Récupérez l’identifiant du compte TikTok sur lequel publier.

curl "$GRIOT_API/workspaces/$WS/accounts" \
  -H "Authorization: Bearer $GRIOT_KEY"

2. Lire les informations du créateur

Obligatoire avant une publication directe : niveaux de confidentialité autorisés, interactions désactivées, durée maximale de vidéo.

curl "$GRIOT_API/workspaces/$WS/accounts/$ACCOUNT_ID/creator-info" \
  -H "Authorization: Bearer $GRIOT_KEY"

# → { "creator_nickname": "…", "creator_avatar_url": "…",
#     "privacy_level_options": ["PUBLIC_TO_EVERYONE", "SELF_ONLY", …],
#     "comment_disabled": false, "duet_disabled": false, "stitch_disabled": true,
#     "max_video_post_duration_sec": 600 }

3. Envoyer un média

Vidéo MP4/MOV jusqu’à 500 Mo, ou image JPG/PNG. La réponse contient l’URL hébergée par Griot.

curl -X POST "$GRIOT_API/workspaces/$WS/media" \
  -H "Authorization: Bearer $GRIOT_KEY" \
  -F "file=@ma-video.mp4"

# → { "url": "…" }

4. Créer une publication

mode « direct » publie sur le profil, « draft » envoie dans les brouillons TikTok. Sans scheduled_at, la publication part tout de suite. external_ref rend l’appel idempotent : renvoyer la même valeur ne crée pas de doublon.

curl -X POST "$GRIOT_API/workspaces/$WS/posts" \
  -H "Authorization: Bearer $GRIOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Nouvelle collection disponible ! #wax #mode",
    "media": [{ "type": "video", "url": "<url renvoyée par /media>" }],
    "targets": [{
      "social_account_id": "<ACCOUNT_ID>",
      "mode": "direct",
      "options": {
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "disable_comment": false,
        "disable_duet": false,
        "disable_stitch": false,
        "brand_content_toggle": false,
        "brand_organic_toggle": true
      }
    }],
    "scheduled_at": "2026-12-01T18:00:00Z",
    "external_ref": "commande-1234"
  }'

# → 201 { "id": "…", "status": "scheduled", … }

5. Suivre l’état

Statuts : draft, scheduled, publishing, published, partial, failed. Chaque compte cible a son propre résultat.

curl "$GRIOT_API/workspaces/$WS/posts?status=failed&page=1&per_page=20" \
  -H "Authorization: Bearer $GRIOT_KEY"

curl "$GRIOT_API/workspaces/$WS/posts/$POST_ID" \
  -H "Authorization: Bearer $GRIOT_KEY"

Webhooks

Griot appelle vos points de terminaison lors des événements post.published et post.failed. Le corps JSON est signé en HMAC-SHA256 avec le secret du point de terminaison ; la signature est dans l’en-tête X-Griot-Signature. Vérifiez-la sur le corps brut, avant tout traitement.

# Python — vérifier la signature sur le corps brut
import hmac, hashlib

def is_valid(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature.removeprefix("sha256="))

# En-tête : X-Griot-Signature
# Événements : post.published, post.failed

La gestion des points de terminaison depuis l’interface arrive bientôt.

Erreurs

Les erreurs renvoient un code HTTP explicite (400, 401, 403, 404, 409, 422, 429) et un corps JSON { "detail": … }. Respectez les limites de débit et réessayez après une erreur 429.

Règles TikTok

Si vous publiez en direct pour le compte d’un utilisateur, votre interface doit respecter les règles de TikTok : afficher le compte, laisser l’utilisateur choisir la visibilité, recueillir son consentement et indiquer les contenus de marque.