Primeiros passos
- Entre na sua conta ServerPrism.
- Abra Conta → Credenciais da API e crie um token.
- Escolha o menor conjunto de scopes de que a sua integração precisa.
- Copie o token uma única vez quando ele aparecer: nunca o guardamos em texto simples e não conseguimos recuperá-lo.
- Use o token como credencial Bearer nos endpoints abaixo.
Todas as requisições vão para https://serverprism.com. Todas as respostas são JSON. Todos os carimbos de data e hora estão em UTC no formato ISO-8601.
Autenticação
Envie o token em um cabeçalho Authorization: Bearer. Os tokens são pessoais: cada um pertence a um único cliente ServerPrism e só pode agir sobre os serviços desse cliente.
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json"Os tokens que você cria pelo painel são tokens de acesso pessoal. Os fluxos OAuth de credenciais de cliente e de código de autorização não estão disponíveis por enquanto para integrações de clientes.
Scopes
Cada token traz um ou mais scopes. Um endpoint exige um scope específico: se faltar, devolve 403.
| Scope | Permite |
|---|---|
servers:read |
Ver os seus servidores (estado, recursos, informações básicas) |
servers:control |
Enviar sinais de energia (iniciar/parar/reiniciar/kill) e comandos de console aos seus servidores |
backups:create |
Criar novos backups dos seus servidores (contam nos seus espaços de backup) |
billing:read |
Ver os dados de faturamento dos seus serviços e as suas faturas (incluindo o download em PDF) |
tickets:read |
Ver os seus tickets de suporte e as respostas |
tickets:write |
Abrir novos tickets de suporte e responder aos seus tickets existentes |
account:read |
Ver os dados básicos da sua conta (nome, endereço de e-mail) |
Limites de uso
Os limites são por minuto e valem duas vezes: uma por token e outra somando todos os tokens da sua conta (vale o que esgotar primeiro). São propositalmente conservadores. Se precisar de mais, abra um ticket e conte-nos sobre a sua integração.
| Bucket | Limite | Endpoints |
|---|---|---|
read |
60 por token, 120 por conta | Todos os endpoints GET, exceto o PDF da fatura |
control |
20 por token, 30 por conta | Energia, comando, criar backup, PDF da fatura |
tickets |
5 por token, 10 por conta; mais 1 ticket novo a cada 30 segundos | Abrir ticket, responder a um ticket |
Exceder um limite devolve 429 Too Many Requests com um cabeçalho Retry-After. Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining para o bucket do token. Aguarde e tente de novo; nunca repita sem pausa diante de um 429.
Erros
Os corpos de erro são JSON com uma message legível e, nos erros próprios da API, um código error estável e legível por máquina, como service_not_active. Os erros de validação (422) incluem também um objeto errors organizado por campo.
| Status | Significado |
|---|---|
| 401 | Token ausente ou inválido. |
| 403 | O token não inclui o scope necessário. |
| 404 | Não encontrado, ou não pertence a você (os dois casos parecem iguais de propósito). |
| 409 | O servidor está em um estado que não permite isso: service_not_active (suspenso, cancelado, pendente), service_paused (armazenamento frio), server_offline, server_busy, backup_limit_reached, backup_in_progress. |
| 422 | O corpo da requisição falhou na validação. |
| 429 | Limite de uso excedido. |
| 503 | O nó de origem está temporariamente indisponível. Tente de novo após uma pequena pausa. |
Endpoints
O ID do servidor nas URLs é o ID numérico do serviço, o mesmo que aparece na sua URL /services/{id}. Todos os caminhos abaixo são relativos a https://serverprism.com/api/v1/client. Os endpoints de lista aceitam page e per_page (máx. 100) e devolvem um bloco meta com total e last_page.
/api/v1/client/serversscope: servers:readLista todos os serviços ativos ou suspensos do titular do token. Barato de consultar: não contata o servidor.
Requisição
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN"Resposta
{
"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:readTudo o que o endpoint de lista devolve, mais o endereço de conexão dos jogadores, as portas do servidor, os limites e o uso de recursos em tempo real (na medida do possível).
Resposta
{
"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
}
}
}O bloco resources pode ser null se o nó esteve brevemente inacessível. Tente de novo ou use o indicador de estado do painel.
/api/v1/client/servers/{id}/powerscope: servers:controlEnvia um sinal de energia ao servidor. Só funciona enquanto o serviço está ativo: serviços suspensos, cancelados ou em pausa devolvem 409.
Corpo da requisição
{
"signal": "start" // one of: "start", "stop", "restart", "kill"
}kill encerra o processo à força, sem dar ao jogo a chance de salvar. Use stop para desligamentos ordenados em jogos com progresso salvo.
Exemplo
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"}'Resposta
{ "data": { "signal": "restart", "sent": true } }/api/v1/client/servers/{id}/commandscope: servers:controlEnvia um único comando de console ao servidor em execução (p. ex. say hello, stop, whitelist add Notch). O servidor precisa estar ligado; caso contrário, você recebe 409 server_offline.
Corpo da requisição
{
"command": "say Server restarting in 5 minutes"
}Uma linha, no máximo 1024 caracteres. Quebras de linha e outros caracteres de controle são rejeitados com 422: envie uma requisição por comando.
Resposta
{ "data": { "command": "say Server restarting in 5 minutes", "sent": true } }/api/v1/client/servers/{id}/backupsscope: servers:readLista os backups do servidor e os seus espaços de backup. Os espaços são compartilhados entre todos os seus servidores e crescem com a RAM do seu plano.
Resposta
{
"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 um backup e devolve 202 na hora. Os backups rodam em segundo plano: consulte o endpoint de lista até que status seja completed ou failed. Cada backup usa um espaço; sem espaços livres, você recebe 409 backup_limit_reached. Os planos de teste não incluem backups (403). Restaurar e excluir backups só é possível no painel.
Corpo da requisição (opcional)
{ "name": "before-1.21-update" }Resposta (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:readResposta
{ "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 os seus serviços em qualquer estado, com os dados de faturamento. Filtro opcional ?status= com um entre pending, provisioning, active, suspended, cancelled, failed.
Resposta
{
"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:readAs suas faturas, da mais recente para a mais antiga. Filtro opcional ?status=pending|paid|cancelled.
Resposta
{
"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 uma fatura, abra o dashboard_url dela. A API nunca movimenta dinheiro.
/api/v1/client/invoices/{id}scope: billing:readOs mesmos campos da lista, mais os itens da fatura. {id} é o id numérico, não o número da fatura.
Resposta (trecho)
{
"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:readBaixa a fatura em PDF (application/pdf), o mesmo documento do botão de download do painel. Conta no bucket de limite control.
curl -o invoice.pdf https://serverprism.com/api/v1/client/invoices/5512/pdf \
-H "Authorization: Bearer YOUR_TOKEN"/api/v1/client/ticketsscope: tickets:readOs seus tickets de suporte, os atualizados mais recentemente primeiro. Filtro opcional ?status=open|replied|closed. replied significa que a nossa equipe respondeu e aguarda você.
Resposta
{
"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:readO ticket e a sua conversa, da mensagem mais antiga para a mais nova. author é you ou staff. Os anexos são listados pelo nome; baixe-os no painel.
Resposta (trecho)
{
"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 um ticket. department é obrigatório e deve ser um dos departamentos exibidos no formulário de novo ticket do painel. priority é low (padrão), medium ou high. service_id é opcional e deve ser um dos seus serviços. Um ticket novo a cada 30 segundos por conta. Devolve 201 com o mesmo corpo de Obter ticket.
Corpo da requisição
{
"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:writeAdiciona a sua resposta a um dos seus tickets (até 20.000 caracteres). Responder a um ticket fechado o reabre, como no painel. Devolve 201 com a nova mensagem.
Corpo da requisição
{ "message": "Still happening tonight, see the timings report." }Não disponível pela API
De propósito, a API não pode pagar, cancelar, fazer upgrade ou downgrade de serviços, aplicar cupons, excluir ou restaurar backups, nem excluir arquivos. Essas ações ficam no painel, onde você vê exatamente o que elas farão antes de confirmar.
Versionamento
O namespace v1 é estável. Mudanças incompatíveis só virão em um novo namespace (v2); podemos acrescentar campos novos às respostas existentes sem aviso, então escreva o seu cliente para ignorar chaves desconhecidas.
Pedidos de recursos e relatos de bugs: abra um ticket e mencione "API".