Referencia de la API

Todo lo que hacen la consola de operador y el portal de cliente pasa por la misma API pública y versionada. Si la interfaz puede hacerlo, un script también puede.

• Ruta base: /api/v1, JSON de entrada y salida.
• Documentación interactiva: un documento OpenAPI 3.1 completo, generado directamente desde los handlers del servidor, se publica en /api/docs sobre el dominio de tu panel.

Autenticación

Dos formas de autenticarse:

Método	Encabezado	Se usa para
Cookie de sesión	Cookie + X-CSRF-Token	La interfaz web en sí
Token de API	Authorization: Bearer opk_...	Scripts, integraciones, sistemas de facturación externos

Crea un token de API en Account → API tokens o con POST /api/v1/api-tokens. Un token tiene permisos específicos y, opcionalmente, queda limitado a un solo cliente; vence (90 días por defecto si no fijás uno, nunca más de un año).

Precaución

Un token nunca puede actuar sobre la cuenta que lo creó. Los permisos son sobre clientes y sitios — nada cubre la cuenta en sí, así que cambiar una contraseña, listar o revocar sesiones, listar o revocar tokens de API, leer segundos factores o gestionar claves SSH rechazan directamente un token y exigen una sesión real, iniciada de forma directa. Un token filtrado es un problema acotado y auditable.

Permisos (scopes)

Permiso	Otorga
customer:read, customer:manage	Leer / modificar datos del cliente
members:manage	Gestionar el equipo de un cliente
billing:read, billing:manage	Leer / modificar facturación y suscripciones
site:read, site:create, site:update, site:delete	Ciclo de vida del sitio
site:files, site:shell	Administrador de archivos/SFTP, y shell/exec/WP-CLI
database:read, database:manage	Bases de datos y usuarios de base de datos
certificate:read, certificate:manage	Certificados TLS personalizados
job:read	Estado y progreso de tareas
audit:read	El registro de auditoría
*	Todos los permisos que tenga el usuario que lo creó

El personal de la plataforma y de las marcas tiene permisos adicionales para sus propias áreas administrativas (nodos, planes, marcas, etc.) — ver el documento OpenAPI en /api/docs para la lista completa y actualizada.

Errores

Los errores siguen RFC 9457 (application/problem+json):

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "One field failed validation.",
  "errors": [
    { "location": "body.limits.diskMB", "message": "Must be at least 0" }
  ]
}

Un rechazo que tiene un motivo específico también lleva un code estable y legible por máquina por cada elemento de errors, así los clientes pueden decidir según ese código en lugar de leer detail.

Paginación

Los endpoints de listado usan paginación por cursor: pasá cursor con el nextCursor de una respuesta anterior para traer la página siguiente. Los listados siempre están filtrados a lo que puede ver quien hace la llamada — un token de API limitado a un cliente nunca ve las filas de otro, pida lo que pida.

Idempotencia

Manda un encabezado Idempotency-Key en las solicitudes POST que crean algo (un sitio, una tarea, un checkout) para que los reintentos sean seguros: repetir la misma solicitud con la misma clave devuelve el resultado original en lugar de crear un duplicado.

Ejemplo

curl https://panel.example.com/api/v1/sites \
  -H "Authorization: Bearer opk_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "018f...",
    "name": "my-site",
    "type": "wordpress",
    "domain": "example.com"
  }'

{
  "id": "018f...",
  "handle": "mysite",
  "type": "wordpress",
  "status": "provisioning",
  "customerId": "018f...",
  "createdAt": "2026-09-24T12:00:00Z"
}

Endpoints útiles para tener a mano

Endpoint	Para qué sirve
GET /api/v1/capabilities	Qué soporta esta instalación, los permisos efectivos de quien llama, y los límites actuales
GET /api/v1/usage	Conteos económicos para dashboards: clientes, sitios, dominios, bases de datos, tráfico reciente
GET /api/v1/audit	El registro de auditoría, filtrable por actor, acción, sujeto y rango de tiempo
GET /api/docs	El documento OpenAPI 3.1 completo

Los webhooks salientes (site.created, job.finished, subscription.suspended, y más) están disponibles para integraciones que prefieren reaccionar a eventos en lugar de hacer polling — configuralos en Admin → Integrations.