Digita no console serial

POST /cloud/servers/{id}/console/{sessionID}/input

Escopo do token: servers:console. Recurso: Console serial.

Textos e teclas nomeadas, na ordem (até 64 itens e 4096 bytes). Não há Ctrl-Alt-Del nem break serial: reset e energia nunca passam pelo console. Toda entrada é registrada com quem digitou (usuário, token de API ou cliente OAuth pelo MCP; o texto guardado cifrado). Com wait_for, espera esse texto na tela por até timeout_seconds (máx. 25) e diz em matched se apareceu. 429 cloud.console_rate_limited acima de 5 envios por segundo (rajada de 30).

Exemplo de requisição

Os exemplos leem o token da variável de ambiente HALVER_API_TOKEN (um token sc_live_… criado em Desenvolvedores › Tokens de API). Nunca escreva o token no código.

curl -X POST "https://dash.halver.com.br/api/v1/cloud/servers/307d7f63-0f00-4d4b-bc28-839d359e13a3/console/a1ae5f0e-3bd9-4f2a-94af-8a07087d0180/input" \
  -H "Authorization: Bearer $HALVER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "input": [
    {
      "text": "uname -a"
    },
    {
      "key": "Enter"
    }
  ],
  "timeout_seconds": 5,
  "wait_for": "GNU/Linux"
}'

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
  "time"
)

func main() {
  body := strings.NewReader(`{
  "input": [
    {
      "text": "uname -a"
    },
    {
      "key": "Enter"
    }
  ],
  "timeout_seconds": 5,
  "wait_for": "GNU/Linux"
}`)
  req, err := http.NewRequest(http.MethodPost, "https://dash.halver.com.br/api/v1/cloud/servers/307d7f63-0f00-4d4b-bc28-839d359e13a3/console/a1ae5f0e-3bd9-4f2a-94af-8a07087d0180/input", body)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("HALVER_API_TOKEN"))
  req.Header.Set("Content-Type", "application/json")
  client := &http.Client{Timeout: 30 * time.Second}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, err := io.ReadAll(resp.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(resp.Status)
  fmt.Println(string(out))
}

import os

import requests

resp = requests.post(
    "https://dash.halver.com.br/api/v1/cloud/servers/307d7f63-0f00-4d4b-bc28-839d359e13a3/console/a1ae5f0e-3bd9-4f2a-94af-8a07087d0180/input",
    headers={
        "Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}",
    },
    json={
        "input": [
            {
                "text": "uname -a",
            },
            {
                "key": "Enter",
            },
        ],
        "timeout_seconds": 5,
        "wait_for": "GNU/Linux",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Parâmetros

Parâmetros do caminho

id string (uuid) obrigatório
Exemplo: 307d7f63-0f00-4d4b-bc28-839d359e13a3.
sessionID string (uuid) obrigatório
Exemplo: a1ae5f0e-3bd9-4f2a-94af-8a07087d0180.

Corpo da requisição

application/json, obrigatório.

input array de object obrigatório
De 1 a 64 itens.
- key string
  Enter, Tab, Esc, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up, Down, Left, Right, Space, F1 a F12, Ctrl-A a Ctrl-Z.
- text string
timeout_seconds integer
De 0 a 25.
wait_for string
Até 200 caracteres.

{
  "input": [
    {
      "text": "uname -a"
    },
    {
      "key": "Enter"
    }
  ],
  "timeout_seconds": 5,
  "wait_for": "GNU/Linux"
}

Respostas

200

A tela depois da entrada.

Campos da resposta

cols integer obrigatório
cursor object obrigatório
- col integer obrigatório
- hidden boolean obrigatório
- row integer obrigatório
idle_deadline string (date-time) obrigatório pode ser nulo
lines array de string obrigatório
As linhas da tela, sem espaços à direita. Saída do servidor (dado não confiável).
matched boolean
Só na entrada com wait_for, se o texto apareceu na tela.
offset integer (int64) obrigatório
rows integer obrigatório
session object obrigatório
- activated_at string (date-time) obrigatório pode ser nulo
- apply_error string obrigatório
- close_reason string obrigatório
  ended pelo cliente; staff pela equipe; idle 15 min sem uso; expired 2 horas; operation uma operação nossa começou no servidor; server_gone o servidor saiu da conta; failed não abriu; engine o broker perdeu a sessão (o SOL caiu). Um de: "" (vazio), ended, staff, idle, expired, operation, server_gone, failed, engine.
- closed_at string (date-time) obrigatório pode ser nulo
- created_at string (date-time) obrigatório
- expires_at string (date-time) obrigatório
- hostname string obrigatório
- id string (uuid) obrigatório
- idle_timeout_seconds integer obrigatório
- input_bytes integer (int64) obrigatório
- input_count integer obrigatório
- opened_by string obrigatório
  Nome de quem abriu.
- opened_via string obrigatório
  Um de: panel, api, mcp.
- server_id string (uuid) obrigatório
- status string obrigatório
  closing = o acesso já terminou; a sessão do broker fecha e a gravação é guardada. Um de: opening, active, closing, closed.
- transcript string obrigatório
  A gravação (asciicast v2) da sessão; saved pode ser baixada. Um de: pending, saved, unavailable.
- transcript_bytes integer (int64) obrigatório

{
  "cols": 80,
  "cursor": {
    "col": 0,
    "hidden": false,
    "row": 0
  },
  "idle_deadline": null,
  "lines": [
    ""
  ],
  "matched": false,
  "offset": 0,
  "rows": 24,
  "session": {
    "activated_at": null,
    "apply_error": "",
    "close_reason": "ended",
    "closed_at": null,
    "created_at": "2026-10-20T18:00:00Z",
    "expires_at": "2026-10-20T18:00:00Z",
    "hostname": "web-01",
    "id": "a1ae5f0e-3bd9-4f2a-94af-8a07087d0180",
    "idle_timeout_seconds": 900,
    "input_bytes": 0,
    "input_count": 0,
    "opened_by": "",
    "opened_via": "panel",
    "server_id": "307d7f63-0f00-4d4b-bc28-839d359e13a3",
    "status": "opening",
    "transcript": "pending",
    "transcript_bytes": 0
  }
}

Erros

Todo erro vem como application/problem+json (RFC 9457), com um code estável, a mensagem em português em detail, o motivo de cada campo em errors (nos erros de validação) e o request_id, que você informa ao suporte. Veja a lista completa de códigos.

Status	Quando	Códigos
400	Requisição inválida (JSON malformado, campo desconhecido, parâmetro inválido ou falha de validação).	`validation_failed`, `request.invalid_json`
401	Não autenticado (token ausente, inválido ou expirado; credenciais inválidas).	`auth.unauthorized`
403	Autenticado, mas sem permissão para a área ou a operação.	`api_token.insufficient_scope`
404	Recurso não encontrado (ou fora do escopo do usuário).	`server.not_found`, `console_session.not_found`
409	Conflito (unicidade ou operação concorrente em andamento).	—
429	Limite de requisições excedido. `Retry-After` diz em quantos segundos cabe a próxima requisição; os limites de taxa também mandam `RateLimit-Policy` e `RateLimit` (draft-ietf-httpapi-ratelimit-headers).	`rate_limited`, `cloud.console_rate_limited`
503	Dependência (gateway de pagamento, consulta de CEP) temporariamente indisponível.	—

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "o token não tem o escopo servers:console; crie um token com esse escopo em Desenvolvedores › Tokens de API",
  "code": "api_token.insufficient_scope",
  "request_id": "6f1c0b2a9e4d7c3b5a8f0e1d"
}