API publique

Aperçu public API

Quand utiliser la surface REST API directement au lieu de la surface MCP.

#Public API aperçu

Le public Showly REST API existe pour les cas où la surface MCP ne convient pas : scripts CI, tableaux de bord personnalisés, intégrations tierces qui ne sont pas des agents.

Si vous écrivez du code d'agent, utilisez plutôt MCP. La surface MCP bénéficie d'un audit de première classe, de jetons étendus et d'entrées de schéma d'outils. Le REST API expose les mêmes actions mais avec une sémantique plus souple conçue pour l'automatisation écrite par l'homme.

URL de base

https://api.showly.ai

Toutes les requêtes nécessitent TLS. Les requêtes HTTP non chiffrées sont rejetées.

Gestion des versions

Il n'y a pas de préfixe /v1/ ni d'en-tête Api-Version aujourd'hui — l'API suit une seule version. Tout changement incompatible est publié dans le journal des modifications, avec la date, la route concernée et une note de migration. Consultez cette page si votre intégration est critique. Les modifications additives (nouveaux champs facultatifs, nouveaux points de terminaison) sont publiées normalement.

Authentification

Chaque requête nécessite un en-tête Authorization: Bearer <token>. Les informations d'identification que vous utiliserez :

  • Jetons d'accès personnels (PAT) — préfixe sk_live_ / sk_test_. Un PAT est limité à l'espace de travail unique dans lequel il a été créé et porte les étendues que vous lui accordez au moment de la création. Pratique pour les scripts ad hoc et CI.
  • MCP jetons — préfixe mcp_live_ / mcp_test_, émis à partir des Paramètres de l'espace de travail → MCP clients ou émis par le flux de l'appareil. Limité à un seul espace de travail et utilisé par la surface MCP ; ils authentifient également les appels REST.

Pour les installations d'agent qui ne peuvent pas coller un jeton statique, Showly prend en charge un flux d'autorisation de périphérique RFC 8628 (POST /oauth/device, puis interroge POST /oauth/token) qui génère un jeton MCP lié à l'utilisateur autorisant. Voir Authentification pour le flux complet et la rotation des jetons.

Enveloppe de réponse

Chaque réponse JSON utilise la même enveloppe. Réponses réussies :

{
  "ok": true,
  "data": { ... }
}

Erreurs :

{
  "ok": false,
  "error": { "code": "string", "message": "string" }
}

error.code est le contrat stable — branchez-le dessus, pas sur error.message. Les codes sont des identifiants en forme de kebab ou de serpent (rate_limited, idempotency_key_conflict, not_found). Les messages sont destinés aux lecteurs humains et peuvent changer d'une version à l'autre.

Limites de taux

Les limites de débit sont sélectionnées dans la liste active de l'espace de travail authentifié. configuration. Les jetons MCP utilisent le plafond conservateur de 60 requêtes/minute quelle que soit la facturation de l’espace de travail. Les routes très sollicitées peuvent avoir des plafonds plus stricts.

Lorsqu'il est limité en débit, le serveur renvoie HTTP 429 avec error.code: "rate_limited" et un en-tête Retry-After transportant le recul en secondes. Traitez Retry-After comme l'attente canonique ; ne réessayez pas plus tôt.

Idempotence

La création d'un déploiement — POST /sites/:siteId/deploy — nécessite un en-tête Idempotency-Key. Sans cela, le serveur renvoie 428. La clé est votre choix ; nous recommandons un UUID par tentative logique. (Les publications de production suivent le même itinéraire avec environment: "production" et un sourceDeploymentId, elles comportent donc la même exigence.) Aucun autre itinéraire ne nécessite l'en-tête.

Les rediffusions de la même clé renvoient la réponse mise en cache du premier appel. Si le corps de la requête change sous la même clé, le serveur renvoie 409 avec idempotency_key_conflict.

Les requêtes GET en lecture seule sont naturellement idempotentes et ignorent l'en-tête.

Pagination

Les points de terminaison de la liste (GET /sites, GET /deployments) renvoient actuellement l'ensemble de résultats complet pour votre espace de travail sous forme de tableau simple — il n'y a pas encore de curseur ou de paramètre limit. Lorsque la pagination sera livrée, elle sera additive (curseurs opaques), annoncée dans le journal des modifications.

Surfaces

  • Authentification — émission et rotation de jetons.
  • Sites — répertorier, créer, inspecter les sites.
  • Déploiements — crée des déploiements, l'état et l'historique des requêtes, diffuse les événements du pipeline.