Comment utiliser l’API publique de Postoria

L’API publique de Postoria vous permet de connecter des outils externes, des scripts et des systèmes internes à Postoria.

Vous pouvez l’utiliser pour connecter et reconnecter des comptes sociaux, lister vos espaces de travail et vos comptes connectés, téléverser des médias, créer et gérer des publications et récupérer leurs statistiques actuelles ou agrégées.

L’API publique est disponible avec les offres Pro et Agency.

Avant de commencer

Voici les principaux points à connaître avant d’utiliser l’API :

Vous devez disposer d’une offre Pro ou Agency active.
Chaque compte Postoria peut avoir une seule clé API active.
Les clés API sont liées au compte, et non à un espace de travail.
Les points de terminaison propres à un espace de travail nécessitent un workspace_id dans l’URL.
L’API utilise une authentification par jeton Bearer.
L’API est limitée à 300 requêtes toutes les 5 minutes par compte.
Le traitement des médias est asynchrone.
Les réponses de l’API utilisent des champs JSON en snake_case.
L’API v1 utilise le préfixe de chemin /v1.

URL de base

Utilisez cette URL de base :

https://api.postoria.io/v1

La documentation de l’API est disponible ici : https://api.postoria.io/v1/docs/.

Le document OpenAPI est disponible ici : https://api.postoria.io/v1/openapi.json.

Créer une clé API

Ouvrez Postoria.
Accédez aux paramètres.
Repérez la section API publique.
Cliquez sur Créer une clé API.
Copiez la clé et conservez-la en lieu sûr.

Postoria n’affiche la clé API complète qu’une seule fois. Après avoir fermé la boîte de dialogue, vous ne verrez plus que le préfixe de la clé.

Si vous perdez la clé, révoquez-la et créez-en une nouvelle.

Authentifier les requêtes

Envoyez la clé API dans l’en-tête Authorization :

Authorization: Bearer pst_live_your_api_key

Exemple :

curl https://api.postoria.io/v1/workspaces \
  -H "Authorization: Bearer pst_live_your_api_key"

Si la clé est absente, non valide ou révoquée, Postoria renvoie 401 invalid_api_key.

Format des réponses

Les réponses portant sur une seule ressource renvoient directement l’objet.

Les réponses de type liste utilisent ce format :

{
  "data": [],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Lorsqu’un point de terminaison de liste prend en charge la pagination, has_more indique si une autre page est disponible. Utilisez next pour demander directement la page suivante, ou transmettez la valeur next_cursor reçue dans le paramètre de requête cursor.

Les réponses d’erreur utilisent ce format :

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Limite de requêtes

L’API publique autorise :

300 requests per 5 minutes per account

Si vous dépassez la limite, Postoria renvoie 429 rate_limit_exceeded avec des en-têtes indiquant quand réessayer.

Exemple :

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1770000000

Points de terminaison

L’API publique v1 comprend les points de terminaison suivants :

GET    /v1/workspaces

GET    /v1/social-account-connection-options
POST   /v1/workspaces/{workspace_id}/social-account-connections
GET    /v1/workspaces/{workspace_id}/social-account-connections/{state}
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

GET    /v1/workspaces/{workspace_id}/social-accounts
PATCH  /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
GET    /v1/workspaces/{workspace_id}/queues

POST   /v1/workspaces/{workspace_id}/media/uploads
POST   /v1/workspaces/{workspace_id}/media/{media_id}/complete
POST   /v1/workspaces/{workspace_id}/media/imports
GET    /v1/workspaces/{workspace_id}/media/{media_id}

POST   /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts/{post_id}
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

GET    /v1/workspaces/{workspace_id}/analytics/posts
GET    /v1/workspaces/{workspace_id}/analytics/post-performance/summary

Lister les espaces de travail

Utilisez ce point de terminaison pour obtenir les espaces de travail accessibles à votre compte :

GET /v1/workspaces

Exemple de réponse :

{
  "data": [
    {
      "id": 1,
      "name": "My Workspace",
      "timezone": "America/New_York"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utilisez l’id renvoyé comme workspace_id dans les points de terminaison propres à un espace de travail.

Connecter ou reconnecter des comptes sociaux

L’API publique utilise un parcours OAuth interactif pour connecter de nouveaux comptes sociaux ou renouveler l’autorisation des comptes existants. Votre application démarre une autorisation, ouvre l’URL du fournisseur renvoyée pour l’utilisateur et vérifie l’état de la connexion une fois que le fournisseur a redirigé l’utilisateur vers Postoria.

Un même parcours d’autorisation peut renvoyer à la fois des comptes nouveaux et existants :

connectable_accounts contient les comptes du fournisseur qui ne sont pas connectés dans l’espace de travail indiqué.
reconnectable_accounts contient les comptes existants de cet espace de travail dont l’autorisation peut être renouvelée grâce à l’autorisation OAuth obtenue.

Après avoir examiné ces listes, appelez le point de terminaison de connexion avec les PID du fournisseur, celui de reconnexion avec les identifiants de compte Postoria, ou les deux si nécessaire.

Lister les options de connexion

Récupérez les réseaux sociaux et les méthodes d’authentification actuellement disponibles via l’API publique :

GET /v1/social-account-connection-options

Exemple de réponse :

{
  "data": [
    {
      "network": "facebook",
      "auth_methods": [
        "facebook_login",
        "meta_business_portfolio"
      ]
    },
    {
      "network": "instagram",
      "auth_methods": [
        "instagram_login",
        "facebook_login",
        "meta_business_portfolio"
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Ne traitez pas cet exemple de réponse comme une liste complète à coder en dur. Utilisez ce point de terminaison comme référence, car les options prises en charge peuvent évoluer.

La version initiale prend en charge les options suivantes :

Réseau	Méthodes d’authentification
`facebook`	`facebook_login`, `meta_business_portfolio`
`instagram`	`instagram_login`, `facebook_login`, `meta_business_portfolio`
`linkedin`	`linkedin_login`
`tumblr`	`tumblr_login`
`youtube`	`google_login`
`pinterest`	`pinterest_login`
`tiktok`	`tiktok_api_for_business`
`google_business_profile`	`google_login`
`threads`	`threads_login`

Démarrer une autorisation

Créez un état de connexion pour un espace de travail :

POST /v1/workspaces/{workspace_id}/social-account-connections

Exemple de requête :

{
  "network": "instagram",
  "auth_method": "instagram_login"
}

Réponse en cas de succès (201 Created) :

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": false,
  "authorization_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_at": "2026-09-07T11:25:28.222872Z"
}

Ouvrez authorization_url dans un navigateur et laissez l’utilisateur suivre le parcours du fournisseur. Le fournisseur redirige le navigateur vers l’URL de rappel hébergée par Postoria, qui enregistre le résultat OAuth associé à state. Votre application n’a pas besoin de fournir une URL de retour ni d’appeler un point de terminaison distinct pour finaliser le parcours.

L’état expire une heure après sa création. Démarrez une nouvelle autorisation si expires_at est dépassé. Un état expiré ou appartenant à un autre espace de travail ou compte Postoria renvoie 404 social_account_connection_not_found.

Vérifier le résultat de l’autorisation

Une fois que l’utilisateur a terminé le parcours du fournisseur, demandez l’état de la connexion :

GET /v1/workspaces/{workspace_id}/social-account-connections/{state}

Vous pouvez interroger régulièrement ce point de terminaison tant que is_completed vaut false. Cette valeur signifie que Postoria n’a pas encore reçu et enregistré le rappel OAuth ; ce champ ne signifie pas que les comptes ont déjà été connectés ou reconnectés.

Exemple de réponse une fois le parcours terminé :

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": true,
  "expires_at": "2026-09-07T11:25:28.222872Z",
  "network": "instagram",
  "auth_method": "instagram_login",
  "error": null,
  "connectable_accounts": [
    {
      "pid": "17841400000000001",
      "name": "Postoria Demo",
      "username": "postoria.demo",
      "description": "Demo account",
      "url": "https://www.instagram.com/postoria.demo/",
      "logo_url": "https://example.com/profile.jpg",
      "account_category": "profile"
    }
  ],
  "reconnectable_accounts": [
    {
      "account_id": 123,
      "pid": "17841400000000002",
      "name": "Postoria",
      "username": "postoria.app",
      "description": "Postoria",
      "url": "https://www.instagram.com/postoria.app/",
      "logo_url": "https://example.com/profile-2.jpg",
      "account_category": "profile"
    }
  ]
}

Si is_completed vaut true et que error n’est pas null, l’autorisation du fournisseur a échoué ou a été refusée. N’appelez aucun des deux points de terminaison d’action sur les comptes ; affichez l’erreur ou démarrez une nouvelle autorisation.

Connecter de nouveaux comptes

Sélectionnez un ou plusieurs PID exactement tels qu’ils sont renvoyés dans connectable_accounts :

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts

Exemple de requête :

{
  "pids": [
    "17841400000000001"
  ]
}

La validation de la requête échoue si un PID n’est pas accessible via cette autorisation ou s’il est déjà connecté dans l’espace de travail.

Reconnecter des comptes existants

Sélectionnez un ou plusieurs identifiants de compte Postoria exactement tels qu’ils sont renvoyés dans reconnectable_accounts :

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

Exemple de requête :

{
  "account_ids": [123, 456]
}

Chaque compte demandé doit appartenir à l’espace de travail et au réseau indiqués, et l’autorisation OAuth obtenue doit y donner accès. Si l’un des comptes demandés n’est pas accessible, l’API renvoie 400 social_accounts_not_available avant de reconnecter les comptes sélectionnés.

Un compte existant peut être reconnecté avec n’importe quelle méthode d’authentification actuellement prise en charge pour son réseau ; elle n’a pas besoin de correspondre à celle utilisée lors de la connexion initiale. Sélectionnez toujours l’account_id renvoyé au lieu de tenter d’établir vous-même la correspondance entre les comptes.

Réponse aux actions sur les comptes

Les points de terminaison de connexion et de reconnexion renvoient tous deux les comptes Postoria concernés :

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "accounts": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app/",
      "metadata": {
        "channel_number": "113"
      }
    }
  ]
}

Lister les comptes sociaux

Utilisez ce point de terminaison pour obtenir les comptes sociaux connectés dans un espace de travail :

GET /v1/workspaces/{workspace_id}/social-accounts

Exemple de réponse :

{
  "data": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app",
      "metadata": {
        "channel_number": "113",
        "owner_account": "acme-media"
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

name est le nom du compte reçu du réseau social. custom_name est un nom facultatif défini dans Postoria. metadata est un objet facultatif contenant des clés et des valeurs de type chaîne de caractères gérées par votre intégration. Les clés des métadonnées conservent leur casse d’origine.

Utilisez les identifiants de compte renvoyés dans social_account_ids lors de la création de publications. Vous pouvez également utiliser les métadonnées pour associer chaque compte connecté à un identifiant stable dans votre propre système.

Utilisez ce point de terminaison pour définir ou mettre à jour le nom personnalisé et les métadonnées d’un compte social connecté :

PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Exemple de requête :

{
  "custom_name": "Channel 113",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Les deux champs sont facultatifs, mais la requête doit en contenir au moins un. Les champs omis restent inchangés.

Points à connaître :

Les espaces en début et en fin de custom_name sont supprimés avant l’enregistrement ; ce champ peut contenir jusqu’à 255 caractères.
Définissez custom_name sur null ou sur une chaîne vide pour ne plus utiliser de nom personnalisé dans l’interface Postoria.
metadata doit être un objet JSON dont les clés et les valeurs sont des chaînes de caractères.
Les métadonnées peuvent contenir jusqu’à 50 entrées. Les clés peuvent comporter jusqu’à 64 caractères et les valeurs jusqu’à 1 024 caractères.
Fournir metadata remplace l’objet de métadonnées complet ; les clés ne sont pas fusionnées individuellement.
Définissez metadata sur null pour le supprimer, ou sur {} pour conserver un objet de métadonnées vide.
Les noms personnalisés et les métadonnées restent associés au compte social Postoria lorsqu’il est reconnecté ou que son autorisation est renouvelée.

Réponse en cas de succès :

{
  "id": 123,
  "name": "Postoria",
  "custom_name": "Channel 113",
  "description": "postoria.app",
  "network": "instagram",
  "url": "https://www.instagram.com/postoria.app",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Si le compte social n’existe pas dans l’espace de travail indiqué, l’API renvoie 404 social_account_not_found.

Utilisez ce point de terminaison pour retirer un compte social connecté d’un espace de travail :

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Le paramètre de requête force est facultatif et vaut false par défaut. Par défaut, le compte ne peut pas être retiré tant qu’il est sélectionné pour des publications dont le statut est scheduled ou queued. Les brouillons ne bloquent pas la suppression.

Si des publications programmées ou en file d’attente subsistent, l’API renvoie 409 social_account_has_scheduled_posts sans modifier le compte ni ses associations avec les publications :

{
  "error": {
    "code": "social_account_has_scheduled_posts",
    "message": "The social account cannot be deleted while scheduled or queued posts remain.",
    "param": null,
    "details": {
      "post_ids": [3001, 3002],
      "has_more": false
    },
    "request_id": "01JEXAMPLE"
  }
}

post_ids contient jusqu’à 10 identifiants de publications bloquantes. Si d’autres publications bloquantes existent, has_more vaut true.

Pour retirer le compte même si des publications programmées ou en file d’attente subsistent, définissez force=true :

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}?force=true

Lorsque la suppression a lieu, Postoria applique le même nettoyage que depuis le tableau de bord. Le compte est retiré des brouillons, des publications programmées et en file d’attente, ainsi que des automatisations connectées. Les publications auxquelles aucun compte social ne reste associé peuvent également être supprimées.

Retirer un compte le déconnecte de l’espace de travail Postoria. Cela ne révoque pas l’autorisation auprès du réseau social. Une requête réussie renvoie 204 No Content. Si le compte social n’existe pas dans l’espace de travail indiqué ou a déjà été retiré, l’API renvoie 404 social_account_not_found.

Lister les files d’attente

Utilisez ce point de terminaison pour obtenir les files d’attente d’un espace de travail :

GET /v1/workspaces/{workspace_id}/queues

Exemple de réponse :

{
  "data": [
    {
      "id": 456,
      "name": "Morning posts",
      "is_paused": false
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utilisez l’identifiant de file d’attente renvoyé lors de la création d’une publication dont publish_mode vaut queue.

Ajouter des médias

Il existe deux façons d’ajouter des médias via l’API :

Créer une URL de téléversement et y envoyer le fichier vous-même.
Importer un média depuis une URL HTTPS publique.

Les deux méthodes créent un objet média. Utilisez le point de terminaison de consultation du statut d’un média pour vérifier quand il est prêt.

Le status d’un média doit être ready avant que vous puissiez le référencer lors de la création d’une publication.

Il existe deux façons de fournir une miniature vidéo :

Image de miniature personnalisée : téléversez ou importez un fichier image via les points de terminaison des médias. Une fois que le média image est ready, transmettez son identifiant dans thumbnail_media_id pour la vidéo dans POST /posts.
Miniature générée à partir d’une image de la vidéo : incluez thumbnail_timestamp_ms lors de la création d’un téléversement vidéo ou d’une importation par URL. La valeur est exprimée en millisecondes. Postoria crée un média image distinct et renvoie son identifiant dans thumbnail_media_id. Attendez que la vidéo et l’image générée soient toutes deux ready, puis transmettez cet identifiant dans POST /posts.

Les formats de téléversement pris en charge comprennent les formats courants d’image, de vidéo et de document, comme JPEG, PNG, WebP, GIF, MP4, MOV et PDF.

Téléverser des médias avec une URL de téléversement

Commencez par créer un téléversement :

POST /v1/workspaces/{workspace_id}/media/uploads

Requête :

{
  "name": "image.jpg",
  "content_type": "image/jpeg"
}

Exemple de réponse :

{
  "id": 9001,
  "status": "waiting_for_upload",
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Pour générer une miniature lors du téléversement direct d’une vidéo, incluez, lors de la création du téléversement, la position temporelle facultative de l’image à extraire :

{
  "name": "video.mp4",
  "content_type": "video/mp4",
  "thumbnail_timestamp_ms": 5000
}

La réponse 201 Created contient l’identifiant du média de la miniature à générer alors que ni la vidéo ni la miniature n’ont encore été entièrement traitées :

{
  "id": 9002,
  "status": "waiting_for_upload",
  "thumbnail_media_id": 9003,
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Envoyez les octets du fichier à l’adresse upload.url renvoyée à l’aide d’une requête HTTP PUT. Transmettez les octets bruts du fichier dans le corps de la requête et utilisez la même valeur content_type que lors de la création du téléversement.

Exemple :

curl -X PUT "https://temporary-upload-url.example" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@image.jpg"

L’URL de téléversement est temporaire. Si elle expire avant que vous ayez envoyé et finalisé le média, créez un nouveau téléversement.

Après avoir envoyé le fichier, finalisez le téléversement :

POST /v1/workspaces/{workspace_id}/media/{media_id}/complete

Exemple de réponse :

{
  "id": 9001,
  "status": "processing",
  "file_id": null,
  "error_code": null,
  "error_message": null
}

Postoria traitera le média en arrière-plan.

Importer des médias depuis une URL

Utilisez ce point de terminaison lorsque le fichier média est déjà accessible à une URL HTTPS publique :

POST /v1/workspaces/{workspace_id}/media/imports

Requête :

{
  "url": "https://example.com/video.mp4",
  "thumbnail_timestamp_ms": 5000
}

Exemple de réponse :

{
  "id": 9002,
  "status": "processing",
  "file_id": null,
  "thumbnail_media_id": 9003,
  "error_code": null,
  "error_message": null
}

Seules les URL HTTPS publiques sont prises en charge. Les URL privées, celles nécessitant une authentification, les fichiers locaux et les chemins relatifs ne sont pas pris en charge.

Dans cet exemple, le média 9002 est la vidéo et le média 9003 est sa miniature générée. Interrogez régulièrement les deux médias jusqu’à ce qu’ils soient prêts. La vidéo source contient thumbnail_media_id, tandis que la miniature générée contient le thumbnail_timestamp_ms demandé.

Le même champ facultatif peut être inclus lors de la création d’un téléversement vidéo direct. Il n’est valide que pour les médias vidéo et sa valeur doit être supérieure ou égale à zéro.

Vérifier le statut d’un média

Utilisez ce point de terminaison pour vérifier si un média est prêt :

GET /v1/workspaces/{workspace_id}/media/{media_id}

Exemple de réponse pour un média prêt :

{
  "id": 9001,
  "status": "ready",
  "file_id": 701,
  "error_code": null,
  "error_message": null
}

Exemple de réponse pour une miniature générée :

{
  "id": 9003,
  "status": "ready",
  "file_id": 702,
  "thumbnail_timestamp_ms": 5000,
  "error_code": null,
  "error_message": null
}

Exemple de réponse en cas d’échec :

{
  "id": 9001,
  "status": "failed",
  "file_id": null,
  "error_code": "media_processing_failed",
  "error_message": "The file format is not supported."
}

Statuts des médias :

waiting_for_upload
processing
ready
failed

Créer une publication

Utilisez ce point de terminaison pour créer une publication :

POST /v1/workspaces/{workspace_id}/posts

L’API ne crée pas de brouillons. Une publication est créée selon l’un de ces modes de publication :

publish_now
schedule
queue

scheduled_time est requis uniquement pour schedule. queue_id est requis uniquement pour queue. Aucun de ces champs ne doit être envoyé pour publish_now.

Tous les comptes sociaux sélectionnés doivent prendre en charge le type de contenu choisi ; sinon, la requête est rejetée.

Exemple de requête pour une publication programmée :

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Post caption",
  "first_comment": "More details in the first comment.",
  "comment_delay": 5,
  "is_ai_generated": true,
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Exemple de réponse :

{
  "id": 3001,
  "status": "scheduled",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": null,
      "error": null
    }
  ],
  "instagram": {
    "content": "image",
    "caption": "Post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ],
    "comment": "More details in the first comment.",
    "comment_delay": 5
  }
}

Les réponses relatives aux publications comprennent un objet pour chaque réseau social activé dans la publication, comme facebook, instagram, linkedin, youtube ou tiktok. Chaque objet de réseau contient :

content : le type de contenu effectif pour ce réseau.
caption : le texte de la légende pour ce réseau.
files : les fichiers médias pour ce réseau. Les URL des fichiers sont des URL signées temporaires, accessibles sans authentification pendant environ une heure. Une vidéo peut également inclure thumbnail_url lorsqu’une miniature est disponible. thumbnail_timestamp_ms est inclus uniquement lorsque la miniature a été générée à partir d’une image de la vidéo.

Exemple de fichier vidéo avec une miniature générée :

{
  "url": "https://assets.postoria.io/w/1/video.mp4?st=temporary_signed_token",
  "thumbnail_url": "https://assets.postoria.io/w/1/thumbnail.png?st=temporary_signed_token",
  "thumbnail_timestamp_ms": 5000
}

Selon le réseau et le type de contenu, un objet de réseau peut également inclure comment et comment_delay, link ou des options de publication propres au réseau. comment_delay est exprimé en minutes. Les publications avec lien et les premiers commentaires ne sont disponibles que si le réseau et le type de contenu sélectionnés les prennent en charge. Les Stories ne prennent pas en charge les premiers commentaires.

Les résultats de publication sont renvoyés par compte dans results lorsqu’ils sont disponibles. Pour les publications programmées et en file d’attente, les résultats peuvent n’être disponibles qu’après le traitement de la publication. Une même publication peut présenter des résultats réussis pour certains comptes et des échecs pour d’autres.

Mention de contenu généré par l’IA

Définissez le champ de premier niveau is_ai_generated sur true lorsque la publication doit porter la mention de contenu généré par l’IA sur les réseaux sociaux compatibles.

{
  "is_ai_generated": true
}

Postoria transmet la mention correspondante lorsque la destination et le type de contenu la prennent en charge :

Comptes Instagram
Publications vidéo TikTok
Vidéos YouTube
Publications X
Épingles Pinterest

Ce paramètre n’est pas transmis pour les publications photo TikTok. Les destinations et les types de contenu non compatibles l’ignorent.

Champs de date et d’heure

Les champs de date et d’heure utilisent des chaînes ISO 8601 en UTC.

Exemple :

"scheduled_time": "2026-06-01T10:00:00Z"

Utilisez l’heure UTC et incluez le Z final.

Si vous programmez une publication à partir d’une heure locale, convertissez-la en UTC avant de l’envoyer à l’API.

Créer une publication immédiate

Définissez publish_mode sur publish_now.

{
  "publish_mode": "publish_now",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Publishing from Postoria Public API"
}

Programmer une publication

Définissez publish_mode sur schedule et fournissez scheduled_time.

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Scheduled from Postoria Public API",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

scheduled_time doit indiquer une date et une heure futures.

Ajouter une publication à une file d’attente

Définissez publish_mode sur queue et fournissez queue_id.

{
  "publish_mode": "queue",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Queued from Postoria Public API",
  "queue_id": 456
}

La file d’attente doit appartenir au même espace de travail.

Types de contenu

Valeurs de content_type prises en charge :

text
image
video
document
carousel
link
story
reel

Si content_type n’est pas fourni, Postoria essaie de le déterminer à partir des données de la requête :

Plusieurs médias → carousel
Un seul média → le type de média correspondant, comme image, video ou document
URL de lien sans média → link
Légende seule → text

La validation propre à chaque réseau social reste applicable. Tous les comptes sociaux sélectionnés doivent prendre en charge le type de contenu demandé ; sinon, l’API renvoie une erreur de validation et ne crée pas la publication.

Ajouter des médias à une publication

Utilisez le tableau media pour référencer les médias créés par les points de terminaison de téléversement ou d’importation. Le status de chaque élément doit être ready.

{
  "media": [
    {
      "media_id": 9001
    }
  ]
}

Pour une vidéo, vous pouvez fournir une miniature facultative. thumbnail_media_id est associé au media_id correspondant et doit référencer un média image prêt.

Pour une miniature personnalisée, téléversez ou importez le fichier image via les points de terminaison des médias et utilisez son identifiant de média.
Pour une miniature générée à partir d’une image de la vidéo, envoyez thumbnail_timestamp_ms lors de la création du téléversement ou de l’importation vidéo, puis utilisez le thumbnail_media_id renvoyé une fois qu’il est ready.

Dans les deux cas, POST /posts reçoit thumbnail_media_id. La position temporelle de l’image à extraire est fournie uniquement à la création du média vidéo, et non à celle de la publication.

{
  "media": [
    {
      "media_id": 9002,
      "thumbnail_media_id": 9003
    }
  ]
}

Publications avec lien

Pour les publications avec lien, fournissez link_url :

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "link",
  "caption": "Useful link",
  "link_url": "https://example.com/article",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Postoria importera les informations du lien à la création de la publication.

Premier commentaire

Utilisez first_comment pour ajouter un premier commentaire lorsque le réseau sélectionné le prend en charge. Utilisez comment_delay pour différer ce premier commentaire ; la valeur est exprimée en minutes.

{
  "first_comment": "More details in the first comment."
}

Les règles propres à chaque réseau restent applicables. Les champs de réponse relatifs au premier commentaire ne sont renvoyés que pour les réseaux qui prennent en charge cette fonctionnalité.

Options Facebook

Utilisez l’objet facebook pour les options propres à Facebook :

{
  "facebook": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true
  }
}

location_id est facultatif et doit être une chaîne numérique positive contenant au maximum 64 chiffres. Il identifie la Page Facebook du lieu physique que Meta doit associer à la publication. Envoyez l’identifiant sous forme de chaîne JSON, et non de nombre, pour préserver exactement les identifiants de grande taille.

Lorsque also_publish_media_to_stories vaut true, Postoria crée d’abord la publication Facebook habituelle, puis publie chaque fichier média joint sous forme de Story Facebook distincte. L’option n’a aucun effet lorsque content_type vaut story ou link.

Options Instagram

Utilisez l’objet instagram pour les options propres à Instagram :

{
  "instagram": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true,
    "collaborators": ["creator_one"],
    "publish_as_trial_reel": false,
    "auto_share_if_performs_well": false,
    "user_tags": [
      {
        "media_id": 9001,
        "username": "creator_one",
        "x": 0.5,
        "y": 0.5
      }
    ]
  }
}

location_id est facultatif et suit le même format que l’option Facebook : une chaîne numérique positive contenant au maximum 64 chiffres. Il doit identifier une Page Facebook associée à un lieu physique.

Lorsque also_publish_media_to_stories vaut true, Postoria crée d’abord la publication Instagram habituelle, puis publie chaque fichier média joint sous forme de Story Instagram distincte. L’option n’a aucun effet lorsque content_type vaut story.

user_tags.media_id doit référencer un média joint à la même publication. Dans les réponses relatives aux publications, les identifications d’utilisateurs utilisent file_id au lieu de media_id.

Options Pinterest

Utilisez l’objet pinterest pour les options propres à Pinterest :

{
  "pinterest": {
    "title": "Pin title",
    "website": "https://example.com/article",
    "alt_text": "A description of the image"
  }
}

website est l’URL de destination de l’Épingle.

Options Google Business Profile

Utilisez l’objet google_business_profile pour ajouter un bouton d’action :

{
  "google_business_profile": {
    "button_type": "LEARN_MORE",
    "button_url": "https://example.com"
  }
}

Les types de boutons pris en charge sont BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP et CALL. Une URL de bouton est requise pour tous les types, sauf CALL.

Paramètres de republication

Utilisez repost pour configurer la republication.

Exemple :

{
  "repost": {
    "frequency": "do_not_repeat",
    "until": null
  }
}

Si vous définissez une fréquence de republication, until doit être une date et une heure UTC futures lorsque les paramètres de republication choisis l’exigent.

Options YouTube

Utilisez l’objet youtube lors de la création de publications pour des comptes YouTube.

Exemple :

{
  "youtube": {
    "title": "Video title",
    "visibility": "public",
    "category": "People & Blogs",
    "made_for_kids": false,
    "video_language": "en",
    "recording_date": "2026-06-01T00:00:00Z",
    "tags": ["tag1", "tag2"]
  }
}

Utilisez les champs YouTube uniquement si au moins un des comptes sociaux sélectionnés est un compte YouTube.

Pour connaître les valeurs YouTube prises en charge, consultez la documentation de l’importation en masse : Comment importer des publications en masse avec un fichier CSV dans Postoria.

Options TikTok

Utilisez l’objet tiktok lors de la création de publications pour des comptes TikTok.

Exemple :

{
  "tiktok": {
    "who_can_watch": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false,
    "disclose_post_content": false,
    "your_brand": false,
    "branded_content": false,
    "photo_title": "Photo title",
    "auto_add_music": false
  }
}

Champs TikTok pris en charge :

who_can_watch : public, followers, friends ou private
allow_comments : true ou false
allow_duet : true ou false
allow_stitch : true ou false
disclose_post_content : true ou false
your_brand : true ou false
branded_content : true ou false
photo_title : texte brut de 90 caractères maximum
auto_add_music : true ou false

Utilisez les champs TikTok uniquement si au moins un des comptes sociaux sélectionnés est un compte TikTok.

Options Tumblr

Utilisez l’objet tumblr pour ajouter des tags natifs Tumblr séparément de la légende de la publication :

{
  "caption": "Explore our latest indie game",
  "tumblr": {
    "tags": ["gaming", "indiegame", "steam", "hades2"]
  }
}

Postoria accepte jusqu’à 30 tags Tumblr. Les espaces au début et à la fin sont supprimés, le # initial est retiré, les valeurs vides sont ignorées et les doublons sont supprimés sans tenir compte de la casse. Un élément du tableau ne peut contenir ni virgule ni guillemet double. Utilisez les options Tumblr uniquement si au moins un des comptes sociaux sélectionnés est un compte Tumblr.

Lister les publications

Utilisez ce point de terminaison pour lister les publications d’un espace de travail :

GET /v1/workspaces/{workspace_id}/posts

Paramètres de requête facultatifs :

account_ids : identifiants des comptes sociaux. Répétez le paramètre ou utilisez des valeurs séparées par des virgules.
queue_id : identifiant de la file d’attente.
status : l’une des valeurs draft, scheduled, in_progress, posted ou queued.
networks : une ou plusieurs valeurs de réseau, comme instagram, facebook, linkedin, youtube ou tiktok.
date_from : date et heure programmées supérieures ou égales à cette valeur UTC.
date_to : date et heure programmées strictement antérieures à cette valeur UTC.
limit : nombre de publications à renvoyer. La valeur par défaut est 25 et le maximum est 100.
cursor : curseur de pagination renvoyé par la page précédente.

account_ids et queue_id doivent appartenir à l’espace de travail indiqué.

Exemple de requête :

curl "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25" \
  -H "Authorization: Bearer pst_live_your_api_key"

Exemple de réponse :

{
  "data": [
    {
      "id": 3001,
      "status": "scheduled",
      "date": "2026-06-01T10:00:00Z",
      "queue_id": null,
      "is_ai_generated": true,
      "results": [
        {
          "account_id": 123,
          "link_to_post": null,
          "error": null
        }
      ],
      "instagram": {
        "caption": "Scheduled post caption",
        "files": [
          {
            "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
          }
        ]
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0",
    "next": "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0"
  }
}

Pour demander la page suivante, appelez directement next ou retransmettez next_cursor dans cursor :

GET /v1/workspaces/{workspace_id}/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0

Vérifier le statut d’une publication

Utilisez ce point de terminaison pour vérifier le statut d’une publication :

GET /v1/workspaces/{workspace_id}/posts/{post_id}

date est l’heure de publication programmée. Elle peut être null pour les publications en file d’attente et les publications immédiates.

Exemple de réponse :

{
  "id": 3001,
  "status": "posted",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": "https://www.instagram.com/p/example",
      "error": null
    }
  ],
  "instagram": {
    "caption": "Published post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ]
  }
}

Statuts des publications :

draft
scheduled
in_progress
posted
queued

Signification des champs de résultat :

link_to_post est renseigné lorsque la publication a réussi et qu’un lien public est disponible.
error est renseigné lorsque la publication a échoué pour ce compte.
link_to_post et error peuvent tous deux être null avant la publication.

Supprimer une publication

Utilisez ce point de terminaison pour supprimer une publication :

DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

Réponse en cas de succès :

204 No Content

La publication doit appartenir à l’espace de travail indiqué.

La suppression retire la publication de Postoria. Elle ne supprime pas les publications déjà diffusées sur les réseaux sociaux. Si la diffusion a déjà commencé, supprimer la publication Postoria n’arrête pas cette diffusion. Les résultats par compte sont supprimés avec la publication et ne peuvent plus être récupérés ensuite.

Obtenir les statistiques de publications précises

Utilisez ce point de terminaison pour récupérer les dernières statistiques disponibles pour un à 100 identifiants de publication Postoria :

GET /v1/workspaces/{workspace_id}/analytics/posts?post_ids=3001&post_ids=3002

Répétez post_ids pour chaque publication. Les identifiants doivent être des entiers positifs. Les doublons sont acceptés et traités comme un seul identifiant.

Chaque publication demandée doit appartenir à l’espace de travail. Si l’une d’elles est absente ou appartient à un autre espace de travail, la requête entière échoue avec 404 post_not_found ; la réponse n’indique pas quels identifiants ont causé l’échec.

Pour les publications Postoria demandées, la réponse contient une ligne par publication externe sur un compte social sélectionné. Les indicateurs sont représentés par des paires nom/valeur, car leur disponibilité varie selon le réseau et peut évoluer :

{
  "data": [
    {
      "post_id": 3001,
      "social_account_id": 123,
      "network": "tiktok",
      "content_type": "video",
      "published_at": "2026-08-01T10:00:00Z",
      "analytics_refreshed_at": "2026-08-25T12:34:56Z",
      "metrics": [
        { "name": "views", "value": 1250 },
        { "name": "likes", "value": 84 }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Les indicateurs indisponibles sont omis. Une valeur connue égale à zéro est renvoyée telle quelle. analytics_refreshed_at est la date et l’heure UTC au format ISO 8601 auxquelles Postoria a actualisé pour la dernière fois avec succès les statistiques de la publication depuis le réseau social. Si une publication existe mais que ses statistiques ne sont pas encore disponibles, analytics_refreshed_at vaut null et metrics est un tableau vide.

Les valeurs de réseau dans les statistiques utilisent des identifiants canoniques comme linkedin, youtube, tiktok et google_business_profile.

Les indicateurs YouTube utilisent des noms distincts préfixés par youtube_. Par exemple : youtube_views, youtube_engaged_views, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched, youtube_average_view_duration et youtube_subscribers_gained. Le point de terminaison des statistiques de publication peut renvoyer aussi bien des indicateurs additifs que des moyennes ou des taux non additifs.

Obtenir une synthèse agrégée des performances des publications

Utilisez ce point de terminaison pour agréger les derniers indicateurs disponibles des publications diffusées pendant un intervalle UTC :

GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary?published_from=2026-08-01T00:00:00Z&published_to=2026-09-01T00:00:00Z&granularity=day&group_by=network

Paramètres de requête obligatoires :

published_from : horodatage UTC ISO 8601 inclusif utilisant Z ou +00:00.
published_to : horodatage UTC ISO 8601 exclusif utilisant Z ou +00:00.

L’intervalle doit être strictement supérieur à zéro et ne peut pas dépasser 366 jours.

Paramètres de requête facultatifs :

granularity : hour, day, month ou year. Omettez ce paramètre pour ne pas répartir les publications en périodes.
group_by : network, content_type ou social_account. Omettez ce paramètre pour ne pas ajouter de dimension de regroupement.

granularity et group_by sont indépendants. Vous pouvez, par exemple, regrouper les résultats par réseau sans découpage temporel, utiliser des périodes quotidiennes sans autre dimension de regroupement, combiner les deux ou omettre les deux pour obtenir une seule ligne de total.

Lorsque granularity est présent, les périodes utilisent le fuseau horaire de l’espace de travail. La réponse inclut ce fuseau IANA et un published_period pour chaque ligne. Les bornes start et end sont des instants UTC, end est exclusive et key est le libellé de la période correspondante dans l’heure locale de l’espace de travail.

{
  "data": [
    {
      "published_period": {
        "start": "2026-08-01T04:00:00Z",
        "end": "2026-08-02T04:00:00Z",
        "key": "2026-08-01"
      },
      "network": "linkedin",
      "post_count": 3,
      "metrics": [
        { "name": "views", "value": 4200 },
        { "name": "comments", "value": 17 }
      ]
    }
  ],
  "timezone": "America/New_York"
}

Si granularity est omis, published_period et le champ de premier niveau timezone sont tous deux omis. Lorsque group_by est omis, aucun champ de regroupement n’est renvoyé. Sinon, chaque ligne contient exactement un champ applicable : network, content_type ou social_account_id.

La synthèse regroupe les publications selon leur date de diffusion. Elle additionne leurs derniers indicateurs disponibles ; elle n’indique pas quand les vues, les réactions ou les autres interactions ont eu lieu. Les totaux égaux à zéro et les totaux d’indicateurs indisponibles sont omis des lignes de synthèse. Les indicateurs non additifs, comme video_skip_rate, video_average_watch_time_milliseconds, les moyennes YouTube et les taux YouTube, sont exclus, car ils ne peuvent pas être additionnés correctement.

Erreurs courantes

Clé API non valide

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Offre requise

{
  "error": {
    "code": "public_api_plan_required",
    "message": "Public API access is available on Pro and Agency plans.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Échec de la validation

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": "content_type",
    "details": {
      "reason": "The selected social account does not support this content type."
    },
    "request_id": "req_abc123"
  }
}

Espace de travail introuvable

{
  "error": {
    "code": "workspace_not_found",
    "message": "The requested workspace was not found.",
    "param": "workspace_id",
    "details": null,
    "request_id": "req_abc123"
  }
}

Bonnes pratiques

Conservez votre clé API en lieu sûr.
N’exposez pas la clé API dans le code frontend.
Téléversez ou importez d’abord les médias, puis attendez que leur statut soit ready.
Utilisez GET /posts/{post_id} pour vérifier le statut après la création d’une publication.
Considérez la liste des noms d’indicateurs comme extensible, au lieu de coder un ensemble fixe en dur.
Utilisez l’UTC pour les filtres de synthèse ; avec granularity, interprétez les clés de période dans le fuseau horaire de l’espace de travail renvoyé.
Gérez les erreurs de validation et affichez le message renvoyé à vos utilisateurs.
Respectez les en-têtes de limitation des requêtes avant de réessayer.
Révoquez immédiatement la clé si vous pensez qu’elle a été exposée.

Comment utiliser l’API publique de Postoria

Avant de commencer

URL de base

Créer une clé API

Authentifier les requêtes

Format des réponses

Limite de requêtes

Points de terminaison

Lister les espaces de travail

Connecter ou reconnecter des comptes sociaux

Lister les options de connexion

Démarrer une autorisation

Vérifier le résultat de l’autorisation

Connecter de nouveaux comptes

Reconnecter des comptes existants

Réponse aux actions sur les comptes

Lister les comptes sociaux

Mettre à jour un compte social

Supprimer un compte social

Lister les files d’attente

Ajouter des médias

Téléverser des médias avec une URL de téléversement

Importer des médias depuis une URL

Vérifier le statut d’un média

Créer une publication

Mention de contenu généré par l’IA

Champs de date et d’heure

Créer une publication immédiate

Programmer une publication

Ajouter une publication à une file d’attente

Types de contenu

Ajouter des médias à une publication

Publications avec lien

Premier commentaire

Options Facebook

Options Instagram

Options Pinterest

Options Google Business Profile

Paramètres de republication

Options YouTube

Options TikTok

Options Tumblr

Lister les publications

Vérifier le statut d’une publication

Supprimer une publication

Obtenir les statistiques de publications précises

Obtenir une synthèse agrégée des performances des publications

Erreurs courantes

Clé API non valide

Offre requise

Échec de la validation

Espace de travail introuvable

Bonnes pratiques