Black Friday: 25 % de descuento de por vida en servidores nuevos con el código .Ver planes

ServerPrism API

Controla tus servidores por código (estado, energía, comandos de consola, copias de seguridad) y lee tus facturas y tickets de soporte desde tus propios scripts, paneles y bots.

¿Usas Claude, Cursor, VS Code u otro asistente de IA? Conéctalo con nuestro servidor MCP: el mismo token, sin código.

Las rutas de los endpoints, los nombres de campo, los códigos de estado y los ejemplos de código se muestran tal como los ve tu código, por eso siguen en inglés en todos los idiomas.

En esta página

Primeros pasos

  1. Inicia sesión en tu cuenta de ServerPrism.
  2. Abre Cuenta → Credenciales de API y crea un token.
  3. Elige el conjunto más pequeño de scopes que necesite tu integración.
  4. Copia el token una sola vez cuando se muestre: nunca lo guardamos en texto plano y no podemos recuperarlo.
  5. Usa el token como credencial Bearer en los endpoints de abajo.

Todas las solicitudes van a https://serverprism.com. Todas las respuestas son JSON. Todas las marcas de tiempo están en UTC con formato ISO-8601.

Autenticación

Envía el token en una cabecera Authorization: Bearer. Los tokens son personales: cada uno pertenece a un único cliente de ServerPrism y solo puede actuar sobre los servicios de ese cliente.

curl https://serverprism.com/api/v1/client/servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Los tokens que creas desde el panel son tokens de acceso personal. Los flujos OAuth de credenciales de cliente y de código de autorización no están disponibles por ahora para integraciones de clientes.

Scopes

Cada token lleva uno o más scopes. Un endpoint exige un scope concreto: si falta, devuelve 403.

Scope Permite
servers:read Ver tus servidores (estado, recursos, información básica)
servers:control Enviar señales de energía (iniciar/detener/reiniciar/kill) y comandos de consola a tus servidores
backups:create Crear nuevas copias de seguridad de tus servidores (cuentan contra tus espacios de copia)
billing:read Ver los datos de facturación de tus servicios y tus facturas (incluida la descarga en PDF)
tickets:read Ver tus tickets de soporte y sus respuestas
tickets:write Abrir nuevos tickets de soporte y responder a tus tickets existentes
account:read Ver los datos básicos de tu cuenta (nombre, correo electrónico)

Límites de uso

Los límites son por minuto y se aplican dos veces: una por token y otra sumando todos los tokens de tu cuenta (vale el que se agote primero). Son deliberadamente conservadores. Si necesitas más, abre un ticket y cuéntanos sobre tu integración.

Bucket Límite Endpoints
read 60 por token, 120 por cuenta Todos los endpoints GET salvo el PDF de la factura
control 20 por token, 30 por cuenta Energía, comando, crear copia de seguridad, PDF de la factura
tickets 5 por token, 10 por cuenta; más 1 ticket nuevo cada 30 segundos Abrir ticket, responder a un ticket

Superar un límite devuelve 429 Too Many Requests con una cabecera Retry-After. Cada respuesta incluye X-RateLimit-Limit y X-RateLimit-Remaining para el bucket del token. Espera y vuelve a intentarlo; nunca repitas sin pausa ante un 429.

Errores

Los cuerpos de error son JSON con un message legible y, en los errores propios de la API, un código error estable y legible por máquinas, como service_not_active. Los errores de validación (422) incluyen además un objeto errors organizado por campo.

Estado Significado
401Falta el token o no es válido.
403El token no incluye el scope necesario.
404No encontrado, o no te pertenece (las dos cosas se ven igual a propósito).
409El servidor está en un estado que no lo permite: service_not_active (suspendido, cancelado, pendiente), service_paused (almacenamiento en frío), server_offline, server_busy, backup_limit_reached, backup_in_progress.
422El cuerpo de la solicitud no superó la validación.
429Límite de uso superado.
503El nodo de origen no está disponible temporalmente. Reintenta tras una breve pausa.

Endpoints

El ID del servidor en las URL es el ID numérico del servicio, el mismo que aparece en tu URL /services/{id}. Todas las rutas de abajo son relativas a https://serverprism.com/api/v1/client. Los endpoints de lista aceptan page y per_page (máx. 100) y devuelven un bloque meta con total y last_page.

Listar servidores
GET/api/v1/client/serversscope: servers:read

Lista todos los servicios activos o suspendidos del titular del token. Barato de consultar: no contacta con el servidor.

Solicitud

curl https://serverprism.com/api/v1/client/servers \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta

{
  "data": [
    {
      "id": 1234,
      "product": "Minecraft 4 GB",
      "service_status": "active",
      "name": "Fred's Minecraft",
      "paused": false,
      "game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
      "expires_at": "2026-11-01T00:00:00+00:00"
    }
  ]
}
Obtener servidor
GET/api/v1/client/servers/{id}scope: servers:read

Todo lo del endpoint de lista más la dirección de conexión que usan los jugadores, los puertos del servidor, sus límites y el uso de recursos en vivo (en la medida de lo posible).

Respuesta

{
  "data": {
    "id": 1234,
    "name": "Fred's Minecraft",
    "service_status": "active",
    "paused": false,
    "game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
    "expires_at": "2026-11-01T00:00:00+00:00",
    "address": "fredcraft.example.com",
    "allocations": [
      { "ip": "203.0.113.7", "port": 25565, "primary": true, "notes": null }
    ],
    "limits": {
      "memory_mb": 4096,
      "disk_mb": 25600,
      "cpu_percent": 200
    },
    "resources": {
      "current_state": "running",
      "memory_bytes": 2147483648,
      "cpu_absolute": 18.5,
      "disk_bytes": 7300000000,
      "network_rx_bytes": 12345678,
      "network_tx_bytes": 87654321,
      "uptime_ms": 3600000
    }
  }
}

El bloque resources puede ser null si el nodo no estuvo accesible un momento. Reintenta o usa el indicador de estado del panel.

Señal de energía
POST/api/v1/client/servers/{id}/powerscope: servers:control

Envía una señal de energía al servidor. Solo funciona mientras el servicio está activo: los servicios suspendidos, cancelados o en pausa devuelven 409.

Cuerpo de la solicitud

{
  "signal": "start"   // one of: "start", "stop", "restart", "kill"
}

kill termina el proceso a la fuerza sin dar al juego la oportunidad de guardar. Usa stop para apagados ordenados en juegos con partida guardada.

Ejemplo

curl -X POST https://serverprism.com/api/v1/client/servers/1234/power \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal":"restart"}'

Respuesta

{ "data": { "signal": "restart", "sent": true } }
Enviar comando
POST/api/v1/client/servers/{id}/commandscope: servers:control

Envía un solo comando de consola al servidor en ejecución (p. ej. say hello, stop, whitelist add Notch). El servidor debe estar en marcha; si no, recibes 409 server_offline.

Cuerpo de la solicitud

{
  "command": "say Server restarting in 5 minutes"
}

Una línea, máximo 1024 caracteres. Los saltos de línea y otros caracteres de control se rechazan con 422: envía una solicitud por comando.

Respuesta

{ "data": { "command": "say Server restarting in 5 minutes", "sent": true } }
Listar copias de seguridad
GET/api/v1/client/servers/{id}/backupsscope: servers:read

Lista las copias de seguridad del servidor y tus espacios de copia. Los espacios se comparten entre todos tus servidores y crecen con la RAM de tu plan.

Respuesta

{
  "data": [
    {
      "uuid": "6f1c0e2a-...",
      "name": "nightly",
      "status": "completed",      // "in_progress" | "completed" | "failed"
      "size_bytes": 734003200,
      "locked": false,
      "created_at": "2026-09-30T03:00:00+00:00",
      "completed_at": "2026-09-30T03:04:12+00:00"
    }
  ],
  "meta": { "quota": { "used": 2, "total": 3, "can_create_more": true, "is_trial": false } }
}
Crear copia de seguridad
POST/api/v1/client/servers/{id}/backupsscope: backups:create

Inicia una copia de seguridad y devuelve 202 de inmediato. Las copias se ejecutan en segundo plano: consulta el endpoint de lista hasta que status sea completed o failed. Cada copia usa un espacio; si no te quedan espacios recibes 409 backup_limit_reached. Los planes de prueba no incluyen copias (403). Restaurar y eliminar copias solo es posible en el panel.

Cuerpo de la solicitud (opcional)

{ "name": "before-1.21-update" }

Respuesta (202)

{ "data": { "uuid": "9a2b...", "name": "before-1.21-update", "status": "in_progress", "size_bytes": 0, "locked": false, "created_at": "2026-10-01T12:00:00+00:00", "completed_at": null } }
Cuenta
GET/api/v1/client/accountscope: account:read

Respuesta

{ "data": { "id": 42, "first_name": "Fred", "last_name": "Smith", "email": "fred@example.com", "email_verified": true, "created_at": "2025-03-01T10:00:00+00:00" } }
Servicios (facturación)
GET/api/v1/client/servicesscope: billing:read

Todos tus servicios en cualquier estado, con los datos de facturación. Filtro opcional ?status= con uno de pending, provisioning, active, suspended, cancelled, failed.

Respuesta

{
  "data": [
    {
      "id": 1234,
      "name": "Fred's Minecraft",
      "product": "Minecraft 4 GB",
      "status": "active",
      "paused": false,
      "plan": { "name": "Monthly", "type": "recurring", "billing_period": 1, "billing_unit": "month" },
      "quantity": 1,
      "price": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "next_due_date": "2026-11-01T00:00:00+00:00",
      "cancellation_requested": false,
      "cancellation_type": null,
      "created_at": "2026-05-01T09:12:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}
Listar facturas
GET/api/v1/client/invoicesscope: billing:read

Tus facturas, las más recientes primero. Filtro opcional ?status=pending|paid|cancelled.

Respuesta

{
  "data": [
    {
      "id": 5512,
      "number": "SP-2026-05512",
      "status": "pending",
      "currency": "EUR",
      "total": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "tax": { "amount": "1.60", "currency": "EUR", "formatted": "€1.60" },
      "remaining": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
      "due_at": "2026-10-04T00:00:00+00:00",
      "created_at": "2026-09-27T00:00:00+00:00",
      "pdf_url": "https://serverprism.com/api/v1/client/invoices/5512/pdf",
      "dashboard_url": "https://serverprism.com/invoices/SP-2026-05512"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}

Para pagar una factura, abre su dashboard_url. La API nunca mueve dinero.

Obtener factura
GET/api/v1/client/invoices/{id}scope: billing:read

Los mismos campos que la lista más las líneas de la factura. {id} es el id numérico, no el número de factura.

Respuesta (extracto)

{
  "data": {
    "id": 5512,
    "status": "pending",
    "items": [
      { "description": "Minecraft 4 GB (Oct 01, 2026 - Nov 01, 2026)", "quantity": 1, "unit_price": "8.00", "total": "8.00", "service_id": 1234 }
    ]
  }
}
PDF de la factura
GET/api/v1/client/invoices/{id}/pdfscope: billing:read

Descarga la factura en PDF (application/pdf), el mismo documento que el botón de descarga del panel. Cuenta contra el bucket de límite control.

curl -o invoice.pdf https://serverprism.com/api/v1/client/invoices/5512/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"
Listar tickets
GET/api/v1/client/ticketsscope: tickets:read

Tus tickets de soporte, los actualizados más recientemente primero. Filtro opcional ?status=open|replied|closed. replied significa que nuestro equipo respondió y espera tu respuesta.

Respuesta

{
  "data": [
    {
      "id": 1301,
      "subject": "Server lagging in the evening",
      "status": "replied",
      "priority": "medium",
      "department": "Support",
      "service_id": 1234,
      "messages_count": 3,
      "last_message_at": "2026-10-01T09:30:00+00:00",
      "created_at": "2026-09-30T18:02:00+00:00",
      "updated_at": "2026-10-01T09:30:00+00:00",
      "dashboard_url": "https://serverprism.com/tickets/1301"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}
Obtener ticket
GET/api/v1/client/tickets/{id}scope: tickets:read

El ticket y su conversación, el mensaje más antiguo primero. author es you o staff. Los adjuntos se listan por nombre; descárgalos desde el panel.

Respuesta (extracto)

{
  "data": {
    "id": 1301,
    "status": "replied",
    "messages": [
      { "id": 9001, "author": "you", "author_name": "Fred Smith", "message": "TPS drops every evening", "attachments": [], "created_at": "2026-09-30T18:02:00+00:00" },
      { "id": 9007, "author": "staff", "author_name": "ServerPrism Support", "message": "We moved you to a quieter host...", "attachments": [], "created_at": "2026-10-01T09:30:00+00:00" }
    ]
  }
}
Abrir ticket
POST/api/v1/client/ticketsscope: tickets:write

Abre un ticket. department es obligatorio y debe ser uno de los departamentos que muestra el formulario de nuevo ticket del panel. priority es low (por defecto), medium o high. service_id es opcional y debe ser uno de tus servicios. Un ticket nuevo cada 30 segundos por cuenta. Devuelve 201 con el mismo cuerpo que Obtener ticket.

Cuerpo de la solicitud

{
  "subject": "Server lagging in the evening",
  "message": "TPS drops to ~12 between 19:00 and 22:00 CET.",
  "department": "Support",
  "priority": "medium",
  "service_id": 1234
}
Responder a un ticket
POST/api/v1/client/tickets/{id}/messagesscope: tickets:write

Añade tu respuesta a uno de tus tickets (hasta 20.000 caracteres). Responder a un ticket cerrado lo reabre, igual que en el panel. Devuelve 201 con el nuevo mensaje.

Cuerpo de la solicitud

{ "message": "Still happening tonight, see the timings report." }

No disponible en la API

A propósito, la API no puede pagar, cancelar, mejorar ni reducir servicios, aplicar cupones, eliminar ni restaurar copias de seguridad, ni borrar archivos. Esas acciones están en el panel, donde ves exactamente qué harán antes de confirmar.

Versionado

El espacio de nombres v1 es estable. Los cambios incompatibles solo llegarán en un espacio nuevo (v2); podemos añadir campos nuevos a las respuestas existentes sin previo aviso, así que escribe tu cliente para que ignore las claves desconocidas.

Solicitudes de funciones e informes de errores: abre un ticket y menciona "API".