Primeros pasos
- Inicia sesión en tu cuenta de ServerPrism.
- Abre Cuenta → Credenciales de API y crea un token.
- Elige el conjunto más pequeño de scopes que necesite tu integración.
- Copia el token una sola vez cuando se muestre: nunca lo guardamos en texto plano y no podemos recuperarlo.
- 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 |
|---|---|
| 401 | Falta el token o no es válido. |
| 403 | El token no incluye el scope necesario. |
| 404 | No encontrado, o no te pertenece (las dos cosas se ven igual a propósito). |
| 409 | El 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. |
| 422 | El cuerpo de la solicitud no superó la validación. |
| 429 | Límite de uso superado. |
| 503 | El 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.
/api/v1/client/serversscope: servers:readLista 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"
}
]
}/api/v1/client/servers/{id}scope: servers:readTodo 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.
/api/v1/client/servers/{id}/powerscope: servers:controlEnví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 } }/api/v1/client/servers/{id}/commandscope: servers:controlEnví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 } }/api/v1/client/servers/{id}/backupsscope: servers:readLista 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 } }
}/api/v1/client/servers/{id}/backupsscope: backups:createInicia 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 } }/api/v1/client/accountscope: account:readRespuesta
{ "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" } }/api/v1/client/servicesscope: billing:readTodos 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 }
}/api/v1/client/invoicesscope: billing:readTus 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.
/api/v1/client/invoices/{id}scope: billing:readLos 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 }
]
}
}/api/v1/client/invoices/{id}/pdfscope: billing:readDescarga 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"/api/v1/client/ticketsscope: tickets:readTus 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 }
}/api/v1/client/tickets/{id}scope: tickets:readEl 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" }
]
}
}/api/v1/client/ticketsscope: tickets:writeAbre 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
}/api/v1/client/tickets/{id}/messagesscope: tickets:writeAñ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".