puxadinho
Criar conta

API

Tudo o que o painel, a CLI e o MCP fazem passa por uma API HTTP com JSON. Use para automações e scripts. São 91 rotas, todas descritas num arquivo OpenAPI

Primeira chamada

Terminal
$ export PUXADINHO_API_KEY=pxd_live_SUA_CHAVE$ curl -H "Authorization: Bearer $PUXADINHO_API_KEY" https://www.usepuxadinho.com.br/v1/boxes

Crie a chave em Conectar ou com puxadinho keys create (veja Chaves e segurança). A chave também vale no cabeçalho X-API-Key.

O contrato

Terminal
$ curl -O https://www.usepuxadinho.com.br/docs/api/openapi.yaml

openapi.yaml (API do puxadinho, versão 1.0.0) é a fonte única: o painel, a CLI e o MCP seguem esse arquivo. Abra num leitor de OpenAPI ou entregue ao seu agente.

O arquivo cita o endereço definitivo da API. Enquanto isso, use https://www.usepuxadinho.com.br como base: as rotas são as mesmas, todas sob /v1.

Regras da casa

  • Mensagens de erro em português (message); códigos em inglês e estáveis (code), bons para o agente decidir o que fazer.
  • Dinheiro em centavos de real, sempre inteiro, em campos que terminam em Cents. Datas em ISO 8601, UTC.
  • Toda mudança numa box vira uma operação op_…. Só uma por box de cada vez: a segunda recebe 409 operation_conflict com Retry-After.
  • Listas vêm em páginas: mande limit e cursor; a resposta traz data e nextCursor.
  • Onde a rota pede {boxId}, vale o id (bx_…) ou o nome da box.
  • Campo desconhecido no corpo dá 400 unknown_field, com uma sugestão do nome certo.

Rotas

Conta

Pessoa logada, login por device code e sessão.

  • GET/v1/meQuem está autenticado
  • POST/v1/auth/deviceIniciar login por device code (CLI) · sem chave
  • POST/v1/auth/device/approveAprovar um device code (painel)
  • POST/v1/auth/device/denyRecusar um device code ("Não fui eu")
  • POST/v1/auth/tokenTrocar device code ou refresh token por sessão · sem chave
  • DELETE/v1/auth/sessionSair (revoga a sessão atual e o refresh token)
  • POST/v1/feedbackEnviar feedback (puxadinho feedback)

Agentes

Auto-cadastro do agente e agentes conectados.

  • POST/v1/agent-registrationsAuto-cadastro do agente (login --agent) · sem chave
  • GET/v1/agent-registrations/{registrationId}Consultar o registro (polling da CLI) · sem chave
  • GET/v1/agent-registrations/claims/{claimCode}Ver o pedido de um código (tela "Confirmar código")
  • POST/v1/agent-registrations/claims/{claimCode}Aprovar o agente (painel ou puxadinho claim XXXX-XXXX)
  • DELETE/v1/agent-registrations/claims/{claimCode}Recusar o pedido
  • POST/v1/agent-registrations/claims/{claimCode}/denyRecusar o pedido ("Não fui eu")
  • GET/v1/agentsAgentes conectados ao workspace
  • DELETE/v1/agents/{agentId}Desconectar agente (revoga a chave dele)

Chaves de API

API keys de workspace (pxd_live_…) com escopos.

  • GET/v1/keysListar API keys do workspace
  • POST/v1/keysCriar API key (o valor aparece só nesta resposta)
  • GET/v1/keys/{keyId}Ver API key
  • DELETE/v1/keys/{keyId}Revogar API key

Boxes

Ciclo de vida das boxes.

  • GET/v1/boxesListar boxes
  • POST/v1/boxesCriar box
  • GET/v1/boxes/{boxId}Ver box
  • PATCH/v1/boxes/{boxId}Renomear, redimensionar, ociosidade, prazos, metadados, tarefa
  • DELETE/v1/boxes/{boxId}Apagar box
  • POST/v1/boxes/{boxId}/startLigar box desligada
  • POST/v1/boxes/{boxId}/stopDesligar box
  • POST/v1/boxes/{boxId}/suspendPôr para dormir (salva a memória)
  • POST/v1/boxes/{boxId}/resumeAcordar box pausada (por qualquer motivo)
  • POST/v1/boxes/{boxId}/restartReiniciar box (aplica resize pendente)
  • POST/v1/boxes/{boxId}/wakeAcordar box pausada pelo sistema
  • POST/v1/boxes/{boxId}/forkCopiar a box em até 5

Operações

Operações assíncronas op_….

  • GET/v1/operationsListar operações
  • GET/v1/operations/{operationId}Ver operação

Execução

Exec, histórico, jobs e processos.

  • POST/v1/boxes/{boxId}/execExecutar comando
  • GET/v1/boxes/{boxId}/executionsHistórico de comandos
  • GET/v1/boxes/{boxId}/executions/{executionId}Ver comando e a saída guardada (últimos 64 KB por stream)
  • GET/v1/boxes/{boxId}/jobsListar jobs
  • POST/v1/boxes/{boxId}/jobsIniciar job em segundo plano
  • GET/v1/boxes/{boxId}/jobs/{jobId}Ver job
  • GET/v1/boxes/{boxId}/jobs/{jobId}/logsSaída do job
  • POST/v1/boxes/{boxId}/jobs/{jobId}/waitEsperar o job terminar
  • POST/v1/boxes/{boxId}/jobs/{jobId}/killEncerrar job
  • GET/v1/boxes/{boxId}/processesProcessos rodando (ps)

Arquivos

Ler, escrever, enviar e baixar arquivos da box.

  • GET/v1/boxes/{boxId}/files/statInformações de um arquivo ou pasta
  • GET/v1/boxes/{boxId}/files/listListar pasta
  • GET/v1/boxes/{boxId}/files/contentLer arquivo (até 64 MB)
  • PUT/v1/boxes/{boxId}/files/contentEscrever arquivo pequeno (até 64 MB)
  • POST/v1/boxes/{boxId}/files/download-urlURL assinada para baixar (qualquer tamanho; pasta como tar.zst até 2 GB)
  • POST/v1/boxes/{boxId}/files/upload-urlURL assinada para um PUT único (até 5 GB; usado pelo MCP)
  • POST/v1/boxes/{boxId}/uploadsAbrir sessão de upload grande (até 50 GB, partes de 32 MB)
  • GET/v1/boxes/{boxId}/uploads/{uploadId}Ver sessão de upload (partes recebidas)
  • DELETE/v1/boxes/{boxId}/uploads/{uploadId}Cancelar sessão de upload
  • POST/v1/boxes/{boxId}/uploads/{uploadId}/completeConcluir upload (confere o sha256 e move para o destino)

Acesso

Portas públicas, SSH, desktop, leases de atividade e logs.

  • GET/v1/boxes/{boxId}/portsPortas publicadas
  • POST/v1/boxes/{boxId}/portsPublicar porta (HTTPS ou TCP com TLS/SNI na 443)
  • DELETE/v1/boxes/{boxId}/ports/{port}Despublicar porta
  • PUT/v1/boxes/{boxId}/activity-leases/{task}Manter a box acordada durante uma espera silenciosa
  • DELETE/v1/boxes/{boxId}/activity-leases/{task}Liberar lease
  • GET/v1/boxes/{boxId}/logsConsole de boot e últimas operações
  • POST/v1/boxes/{boxId}/ssh-certificatesEmitir certificado SSH de vida curta
  • POST/v1/boxes/{boxId}/desktop-sessionAbrir o desktop (noVNC) com token de sessão

Snapshots

Salvar e restaurar o estado das boxes.

  • POST/v1/boxes/{boxId}/restoreRestaurar um snapshot no lugar
  • POST/v1/boxes/{boxId}/snapshotsSalvar snapshot da box
  • GET/v1/snapshotsListar snapshots
  • GET/v1/snapshots/{snapshotId}Ver snapshot
  • DELETE/v1/snapshots/{snapshotId}Apagar snapshot
  • GET/v1/snapshots/{snapshotId}/filesVer arquivos de um snapshot

Templates

Modelos de box (padrao, midia).

  • GET/v1/templatesListar templates e versões
  • GET/v1/templates/{templateName}Ver template

Workspaces

Workspaces, pessoas, convites, uso, limite de gasto e plano.

  • GET/v1/orgsWorkspaces acessíveis
  • POST/v1/orgsCriar workspace de time
  • GET/v1/orgs/{orgId}Ver workspace
  • PATCH/v1/orgs/{orgId}Renomear workspace
  • GET/v1/orgs/{orgId}/membersPessoas do workspace
  • PATCH/v1/orgs/{orgId}/members/{userId}Mudar papel
  • DELETE/v1/orgs/{orgId}/members/{userId}Remover pessoa
  • GET/v1/orgs/{orgId}/invitesConvites pendentes
  • POST/v1/orgs/{orgId}/invitesConvidar pessoa por e-mail
  • DELETE/v1/orgs/{orgId}/invites/{inviteId}Cancelar convite
  • POST/v1/invites/{inviteToken}/acceptAceitar convite (pessoa logada)
  • GET/v1/orgs/{orgId}/usageUso e custo do mês (centavos de real)
  • GET/v1/orgs/{orgId}/spend-limitLimite de gasto mensal
  • PUT/v1/orgs/{orgId}/spend-limitDefinir limite de gasto mensal
  • GET/v1/orgs/{orgId}/billingPlano, forma de pagamento e dados da nota (sem detalhes do provedor)
  • GET/v1/orgs/{orgId}/invoicesFaturas e notas

Secrets

Chaves de outros serviços, injetadas pelo proxy. O valor nunca volta.

  • PUT/v1/boxes/{boxId}/secretsEscolher quais Secrets a box pode usar
  • GET/v1/orgs/{orgId}/secretsListar Secrets (só metadados)
  • GET/v1/orgs/{orgId}/secrets/{secretName}Ver Secret (só metadados)
  • PUT/v1/orgs/{orgId}/secrets/{secretName}Criar ou trocar Secret (valor só de escrita)
  • DELETE/v1/orgs/{orgId}/secrets/{secretName}Apagar Secret

Eventos

Stream de eventos em tempo real para o painel.

  • GET/v1/eventsEventos em tempo real (Server-Sent Events)