Black Friday: 25% de desconto vitalício em servidores novos com o código .Ver planos

ServerPrism API

Controle os seus servidores por código (estado, energia, comandos de console, backups) e leia as suas faturas e tickets de suporte a partir dos seus próprios scripts, painéis e bots.

Você usa Claude, Cursor, VS Code ou outro assistente de IA? Conecte-o ao nosso servidor MCP: o mesmo token, sem código.

Os caminhos dos endpoints, os nomes dos campos, os códigos de estado e os exemplos de código aparecem tal como o seu código os vê, por isso ficam em inglês em todos os idiomas.

Nesta página

Primeiros passos

  1. Entre na sua conta ServerPrism.
  2. Abra Conta → Credenciais da API e crie um token.
  3. Escolha o menor conjunto de scopes de que a sua integração precisa.
  4. Copie o token uma única vez quando ele aparecer: nunca o guardamos em texto simples e não conseguimos recuperá-lo.
  5. 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
401Token ausente ou inválido.
403O token não inclui o scope necessário.
404Não encontrado, ou não pertence a você (os dois casos parecem iguais de propósito).
409O 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.
422O corpo da requisição falhou na validação.
429Limite de uso excedido.
503O 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.

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

Lista 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"
    }
  ]
}
Obter servidor
GET/api/v1/client/servers/{id}scope: servers:read

Tudo 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.

Sinal de energia
POST/api/v1/client/servers/{id}/powerscope: servers:control

Envia 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 } }
Enviar comando
POST/api/v1/client/servers/{id}/commandscope: servers:control

Envia 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 } }
Listar backups
GET/api/v1/client/servers/{id}/backupsscope: servers:read

Lista 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 } }
}
Criar backup
POST/api/v1/client/servers/{id}/backupsscope: backups:create

Inicia 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 } }
Conta
GET/api/v1/client/accountscope: account:read

Resposta

{ "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" } }
Serviços (faturamento)
GET/api/v1/client/servicesscope: billing:read

Todos 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 }
}
Listar faturas
GET/api/v1/client/invoicesscope: billing:read

As 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.

Obter fatura
GET/api/v1/client/invoices/{id}scope: billing:read

Os 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 }
    ]
  }
}
PDF da fatura
GET/api/v1/client/invoices/{id}/pdfscope: billing:read

Baixa 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"
Listar tickets
GET/api/v1/client/ticketsscope: tickets:read

Os 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 }
}
Obter ticket
GET/api/v1/client/tickets/{id}scope: tickets:read

O 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" }
    ]
  }
}
Abrir ticket
POST/api/v1/client/ticketsscope: tickets:write

Abre 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
}
Responder a um ticket
POST/api/v1/client/tickets/{id}/messagesscope: tickets:write

Adiciona 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".