Desarrolladores
Referencia de API
Autentíquese con una sesión o clave API y utilice los endpoints implementados de cuenta, cotización, instancia y facturación.
8 min de lectura · ActualizadoAutenticación
La ruta base es /api/v1. Las solicitudes del navegador utilizan la cookie de sesión HttpOnly creada al iniciar sesión. Los scripts pueden usar Authorization: Bearer seguido de una clave API activa. Las claves tienen permisos completos de la cuenta y se muestran una sola vez al crearlas.
La interfaz local utiliza claves gh_demo_. Revocar una clave impide inmediatamente nuevas solicitudes autenticadas que la utilicen. No ponga claves en URL ni en paquetes del lado del navegador.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Reglas de solicitud y reintento
Los cuerpos de POST y PATCH son objetos JSON, con Content-Type: application/json. Envíe {} para acciones sin parámetros. Los cuerpos están limitados a 32 KiB de texto. Las respuestas usan Cache-Control: no-store.
El despliegue, la renovación manual y la retirada requieren una Idempotency-Key de 8–128 caracteres. Use una clave nueva para una nueva operación prevista y reutilice la misma clave para su reintento. Nunca la reutilice con un cuerpo diferente. Una respuesta de repetición incluye replayed: true.
Las cotizaciones de instancia calculan el precio actual del catálogo sin reservar capacidad. Envíe expectedPriceCents al desplegar; una discrepancia devuelve 409 para que el precio pueda revisarse de nuevo.
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
}Endpoints implementados
Todos los recursos de la cuenta están restringidos a su propietario. El endpoint de disponibilidad es público y expone la instantánea del catálogo, no una sonda de hardware en vivo.
| Método | Ruta después de /api/v1 | Propósito |
|---|---|---|
| POST | /auth/register · /auth/login | Nombre de usuario + contraseña; crear una sesión |
| POST | /auth/recover | Nombre de usuario + código no utilizado + nueva contraseña |
| POST | /auth/logout | Revocar la sesión actual del navegador |
| GET | /me · /balance · /ledger | Cuenta, saldo y últimas 100 entradas |
| GET / DELETE | /sessions · /sessions/:id | Listar sesiones activas o revocar una |
| GET | /availability | Catálogo público e instantánea regional de existencias |
| GET / POST | /deposit-quotes | Enumere las cotizaciones activas o cree una con asset + desiredUsdCents |
| POST | /demo/confirm-deposit | ID de presupuesto; solo desarrollo local |
| GET | /deposits · /withdrawals | Últimos 100 registros de esta cuenta |
| POST | /withdrawals | Activo + destino + amountUsdCents; idempotente |
| POST | /instance-quotes | GPU, cantidad, región, imagen, período y opciones |
| GET / POST | /instances | Enumere las asignaciones o implemente; la implementación es idempotente |
| POST | /instances/:id/start · stop · release · renew | Acción de ciclo de vida; la renovación es idempotente |
| PATCH | /instances/:id/auto-renew | Establezca enabled en true o false |
| GET / POST | /ssh-keys · /api-keys | Listar o crear claves de cuenta |
| DELETE | /ssh-keys/:id · /api-keys/:id | Revocar una clave |
Gestione los errores de forma explícita
Los errores tienen {error, message}: un código estable y una explicación legible. 400 indica entrada no válida, 401 autenticación ausente o no válida, 403 un origen rechazado, 404 un recurso desconocido o sin propietario, 409 un conflicto de saldo/state/duplicate y 415 el tipo de contenido incorrecto.
Para una cotización de depósito vencida, crea otra cotización. Para un estado de instancia modificado, recarga la instancia antes de decidir otra acción. Tras una interrupción de red, reutiliza la clave de operación en lugar de crear un segundo cargo.