Referência da API da Clousd.

Todas as rotas da API v1 da Clousd, 71 operações, agrupadas do jeito que você vai usá-las. Parâmetros, corpos de requisição e respostas estão no arquivo OpenAPI.

Ler a documentação Baixar OpenAPI

Toda requisição

# base URL
https://api.clousd.com/v1

# header
Authorization: Bearer cl_live_your_key

# errors are JSON
{ "error": "busy", "message": "…" }

Todas as rotas.

Tarefas · 20 Aparelhos · 13 Agentes de IA · 3 Tela e entrada · 7 Rede · 3 Apps · 4 ADB · 3 Arquivos e mídia · 5 Webhooks · 8 Conta · 5

Básico

O quê	Valor	Observações
URL base	https://api.clousd.com/v1	Só HTTPS, JSON na entrada e na saída
Autenticação	Authorization: Bearer cl_live_…	As chaves são criadas no painel, com escopo read ou control e uma lista de aparelhos
Operações longas	202 Accepted → GET /v1/jobs/{id}	Criar, iniciar, restaurar e chamadas parecidas retornam um job para consultar
Erros	{ "error": "busy", "message": "…" }	Um código curto para o seu código decidir e uma mensagem para pessoas
Especificação completa	openapi-v1.yaml	OpenAPI 3.1 com parâmetros, corpos e respostas

Tarefas

Método	Rota	O que faz
GET	/v1/schedules	Agendas desta chave
POST	/v1/schedules	Uma tarefa que roda sozinha: todo dia, de hora em hora ou quando você chamar
POST	/v1/schedules/{id}/toggle	Pausar ou retomar uma agenda
POST	/v1/schedules/{id}/delete	Excluir uma agenda
POST	/v1/runs	Dar a um ou vários celulares uma tarefa em palavras simples
GET	/v1/runs	Execuções desta chave, as mais novas primeiro
GET	/v1/runs/{id}	Uma execução: status, answer, structured_output e o card em que ela espera
DELETE	/v1/runs/{id}	Excluir uma execução concluída com seus passos e capturas de tela
GET	/v1/runs/{id}/events	Eventos ao vivo via Server-Sent Events
GET	/v1/runs/{id}/trajectory	Cada passo: ferramenta, alvo, resultado e se a tela foi guardada
GET	/v1/runs/{id}/steps/{n}.jpg	A tela antes do passo n
POST	/v1/runs/{id}/answer	Responder ao card da execução: uma pergunta (answer) ou uma permissão (allow / decline)
POST	/v1/runs/{id}/message	Dizer algo ao agente em execução; ele lê antes do próximo passo
POST	/v1/runs/{id}/cancel	Interromper a execução
POST	/v1/schedules/{id}/run	Iniciar uma agenda agora: o gatilho para trigger=api
GET	/v1/credentials	Logins salvos: pacote, nome e quais campos estão preenchidos; os valores nunca são retornados
POST	/v1/credentials	Salvar um login para um app
POST	/v1/credentials/{id}/fields	Definir um campo de um login
DELETE	/v1/credentials/{id}/fields/{type}	Remover um campo de um login
DELETE	/v1/credentials/{id}	Excluir um login

Aparelhos

Método	Rota	O que faz
GET	/v1/devices	Aparelhos que esta chave vê
POST	/v1/devices	Criar um aparelho (cobrado da conta da chave de API)
GET	/v1/devices/{name}	Um aparelho
POST	/v1/devices/{name}/start	Iniciar o aparelho
POST	/v1/devices/{name}/stop	Parar o aparelho (o estado é mantido; um aparelho parado não custa nada)
POST	/v1/devices/{name}/restart	Reiniciar o aparelho
GET	/v1/devices/{name}/ice	Servidores ICE para um visualizador WebRTC deste aparelho: o TURN do host do aparelho com uma credencial temporária (basta uma chave read)
GET	/v1/devices/{name}/quality	Qualidade por categoria (última medição)
POST	/v1/devices/{name}/reset	Redefinir o aparelho para um estado limpo: apps e dados são apagados e o celular volta como novo (mesmo modelo e Android, 1-5 min)
GET	/v1/devices/{name}/screenrecord	Gravar a tela por alguns segundos
POST	/v1/devices/{name}/label	Dar ao celular um nome que pessoas e agentes consigam distinguir (“Pixel QA”); vazio = volta a “Modelo #N”
GET	/v1/balance	O dinheiro da conta: saldo, gasto por dia, horas restantes, renovações e avisos para mostrar ao usuário
GET	/v1/models	Modelos a partir dos quais você pode criar aparelhos

Agentes de IA

Método	Rota	O que faz
GET	/v1/devices/{name}/observe	Um olhar novo no celular: captura de tela, árvore da interface e o app na tela em uma só chamada
POST	/v1/devices/{name}/act	Uma ação e depois esperar a tela estabilizar
POST	/v1/devices/{name}/op	Uma primitiva do núcleo (o protocolo do núcleo Lusiesta, um para um)

Tela e entrada

Método	Rota	O que faz
GET	/v1/devices/{name}/screenshot	Tela em PNG; com w, um JPEG menor (em cache por até 10 s; use /observe para um quadro novo)
POST	/v1/devices/{name}/action	Uma ação no celular (sem esperar)
POST	/v1/devices/{name}/input	Toque, tecla, texto, rolagem, área de transferência, rotação (precisa de uma sessão de transmissão ao vivo)
GET	/v1/devices/{name}/logs	Últimas linhas do logcat
GET	/v1/devices/{name}/stream	Números da transmissão ao vivo: fps, taxa de bits, atraso do visualizador, degrau do ABR (basta uma chave read)
POST	/v1/devices/{name}/stream	WebRTC: entra uma oferta SDP, sai uma resposta SDP; um corpo com bitrate_kbps fixa o degrau de qualidade em vez disso (chave control)
POST	/v1/devices/{name}/stream/probe	Teste de latência para um visualizador ao vivo: puxa a aba de notificações por 600 ms e retorna o relógio do gateway (chave control, no máximo uma vez a cada 5 s por aparelho)

Rede

Método	Rota	O que faz
GET	/v1/devices/{name}/network	País de rede do aparelho
POST	/v1/devices/{name}/network	Definir o país de onde o aparelho se conecta (fuso horário e idioma acompanham)
GET	/v1/network/options	O que pode ser escolhido agora ao criar um aparelho: países e planos

Apps

Método	Rota	O que faz
POST	/v1/devices/{name}/apk	Instalar um APK
GET	/v1/apps	Catálogo de apps: o que pode ser instalado agora
GET	/v1/devices/{name}/apps	Apps do catálogo instalados no aparelho
POST	/v1/devices/{name}/apps	Instalar um app do catálogo (chave control)

ADB

Método	Rota	O que faz
GET	/v1/devices/{name}/adb	Status da sessão ADB
POST	/v1/devices/{name}/adb	Abrir uma sessão ADB pelo relay (código
DELETE	/v1/devices/{name}/adb	Fechar a sessão ADB

Arquivos e mídia

Método	Rota	O que faz
PUT	/v1/devices/{name}/files	Colocar um arquivo no celular (push): o corpo é o arquivo, caminho em /sdcard/ ou /data/local/tmp/
POST	/v1/devices/{name}/media	Mídia da biblioteca no celular como se tivesse sido feita com ele (push), remover o que colocamos (clean) ou listar
GET	/v1/media	A biblioteca de mídia: fotos e vídeos com seus ids
POST	/v1/media	Enviar uma foto ou um vídeo: {name, data_b64, folder}, até 25 MB
POST	/v1/media/send	Copiar arquivos da biblioteca para as galerias dos celulares

Webhooks

Método	Rota	O que faz
GET	/v1/webhooks	Webhooks desta chave e os eventos que você pode assinar (run.completed / failed / cancelled / waiting, device.problem / resolved)
POST	/v1/webhooks	Assinar uma URL https
GET	/v1/webhooks/{id}	Um webhook
DELETE	/v1/webhooks/{id}	Excluí-lo
POST	/v1/webhooks/{id}/rotate	Segredo novo (mostrado uma vez)
POST	/v1/webhooks/{id}/toggle	Pausar ou retomar as entregas
POST	/v1/webhooks/{id}/test	Enviar um evento de teste agora
GET	/v1/webhooks/{id}/deliveries	Entregas recentes com status e tempo de resposta

Conta

Método	Rota	O que faz
GET	/v1/usage	Minutos ligados por aparelho por dia (UTC) em um mês
GET	/v1/incidents	Incidentes nos seus aparelhos (os últimos 100, os mais novos primeiro)
GET	/v1/health	Saúde dos seus aparelhos (medida a cada 5 minutos)
GET	/v1/jobs	Últimos 50 jobs dos seus aparelhos
GET	/v1/jobs/{id}	Estado de uma operação longa