Développeurs
Référence API
Authentifiez-vous avec une session ou une clé API et utilisez les points de terminaison implémentés pour les comptes, les devis, les instances et la facturation.
8 min de lecture · Mis à jour leAuthentification
Le chemin de base est /api/v1. Les requêtes du navigateur utilisent le cookie de session HttpOnly créé à la connexion. Les scripts peuvent utiliser Authorization: Bearer suivi d'une clé API active. Les clés disposent de toutes les autorisations du compte et ne sont affichées qu'une seule fois lors de leur création.
L'interface locale utilise des clés gh_demo_. La révocation d'une clé empêche immédiatement les nouvelles requêtes authentifiées qui l'utilisent. Ne placez pas les clés dans les URL ou les bundles côté navigateur.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Règles de requête et de nouvelle tentative
Les corps POST et PATCH sont des objets JSON, avec Content-Type : application/json. Envoyez {} pour les actions sans paramètres. Les corps sont limités à 32 Kio de texte. Les réponses utilisent Cache-Control : no-store.
Le déploiement, le renouvellement manuel et le retrait nécessitent un Idempotency-Key de 8 à 128 caractères. Utilisez une nouvelle clé pour une nouvelle opération prévue et réutilisez la même clé pour sa nouvelle tentative. Ne la réutilisez jamais avec un corps différent. Une réponse rejouée inclut replayed: true.
Les devis d'instance calculent le prix actuel du catalogue sans réserver de capacité. Envoyez expectedPriceCents lors du déploiement ; une divergence renvoie 409 afin que le prix puisse être réexaminé.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}Points de terminaison implémentés
Toutes les ressources du compte sont limitées à leur propriétaire. Le point de terminaison de disponibilité est public et expose un instantané du catalogue, pas une sonde matérielle en direct.
| Méthode | Chemin après /api/v1 | Objet |
|---|---|---|
| POST | /auth/register · /auth/login | Nom d'utilisateur + mot de passe ; créer une session |
| POST | /auth/recover | Nom d'utilisateur + code inutilisé + nouveau mot de passe |
| POST | /auth/logout | Révoquer la session de navigateur actuelle |
| GET | /me · /balance · /ledger | Compte, solde et dernières 100 écritures |
| GET / DELETE | /sessions · /sessions/:id | Lister les sessions actives ou en révoquer une |
| GET | /availability | Catalogue public et instantané régional du stock |
| GET / POST | /deposit-quotes | Lister les devis actifs ou en créer un avec les paramètres asset et desiredUsdCents |
| POST | /demo/confirm-deposit | ID de devis ; développement local uniquement |
| GET | /deposits · /withdrawals | Derniers 100 enregistrements pour ce compte |
| POST | /withdrawals | Actif + destination + amountUsdCents ; idempotent |
| POST | /instance-quotes | GPU, quantité, région, image, période et options |
| GET / POST | /instances | Lister les allocations ou déployer ; le déploiement est idempotent |
| POST | /instances/:id/start · stop · release · renew | Action de cycle de vie ; le renouvellement est idempotent |
| PATCH | /instances/:id/auto-renew | Définir enabled sur true ou false |
| GET / POST | /ssh-keys · /api-keys | Lister ou créer des clés de compte |
| DELETE | /ssh-keys/:id · /api-keys/:id | Révoquer une clé |
Gérez les erreurs explicitement
Les erreurs ont {error, message} : un code stable et une explication lisible. 400 indique une entrée invalide, 401 une authentification manquante ou invalide, 403 une origine rejetée, 404 une ressource inconnue ou non possédée, 409 un conflit de solde/state/duplicate, et 415 un type de contenu incorrect.
Pour un devis de dépôt expiré, créez un autre devis. Pour un état d'instance modifié, rechargez l'instance avant de décider d'une autre action. Après une interruption réseau, réutilisez la clé d'opération plutôt que de créer un second débit.