OpenHands/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/cloud/cloud-api.md

API da OpenHands Cloud

A OpenHands Cloud fornece uma API REST que permite interagir programaticamente com o serviço. Isso é útil se você deseja iniciar facilmente seus próprios trabalhos a partir de seus programas de maneira flexível.

Este guia explica como obter uma chave de API e usar a API para iniciar conversas. Para informações mais detalhadas sobre a API, consulte a Referência da API OpenHands.

Obtendo uma Chave de API

Para usar a API da OpenHands Cloud, você precisará gerar uma chave de API:

1. Faça login na sua conta OpenHands Cloud
2. Navegue até a página de Configurações
3. Localize a seção "API Keys"
4. Clique em "Generate New Key"
5. Dê à sua chave um nome descritivo (ex: "Desenvolvimento", "Produção")
6. Copie a chave de API gerada e armazene-a com segurança - ela será mostrada apenas uma vez

Uso da API

Iniciando uma Nova Conversa

Para iniciar uma nova conversa com a OpenHands realizando uma tarefa, você precisará fazer uma requisição POST para o endpoint de conversas.

Parâmetros da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
initial_user_msg	string	Sim	A mensagem inicial para começar a conversa
repository	string	Não	Nome do repositório Git para fornecer contexto no formato proprietário/repo. Você deve ter acesso ao repositório.

Exemplos

cURL

curl -X POST "https://app.all-hands.dev/api/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
    "repository": "yourusername/your-repo"
  }'

Python (com requests)

import requests

api_key = "YOUR_API_KEY"
url = "https://app.all-hands.dev/api/conversations"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
    "repository": "yourusername/your-repo"
}

response = requests.post(url, headers=headers, json=data)
conversation = response.json()

print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['id']}")
print(f"Status: {conversation['status']}")

TypeScript/JavaScript (com fetch)

const apiKey = "YOUR_API_KEY";
const url = "https://app.all-hands.dev/api/conversations";

const headers = {
  "Authorization": `Bearer ${apiKey}`,
  "Content-Type": "application/json"
};

const data = {
  initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
  repository: "yourusername/your-repo"
};

async function startConversation() {
  try {
    const response = await fetch(url, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(data)
    });

    const conversation = await response.json();

    console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
    console.log(`Status: ${conversation.status}`);

    return conversation;
  } catch (error) {
    console.error("Error starting conversation:", error);
  }
}

startConversation();

Resposta

A API retornará um objeto JSON com detalhes sobre a conversa criada:

{
  "status": "ok",
  "conversation_id": "abc1234",
}

Você também pode receber um AuthenticationError se:

1. Você forneceu uma chave de API inválida
2. Você forneceu o nome do repositório errado
3. Você não tem acesso ao repositório

Recuperando o Status da Conversa

Você pode verificar o status de uma conversa fazendo uma requisição GET para o endpoint de conversas.

Endpoint

GET https://app.all-hands.dev/api/conversations/{conversation_id}

Exemplo

cURL

curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

A resposta é formatada da seguinte forma:

{
  "conversation_id":"abc1234",
  "title":"Update README.md",
  "created_at":"2025-04-29T15:13:51.370706Z",
  "last_updated_at":"2025-04-29T15:13:57.199210Z",
  "status":"RUNNING",
  "selected_repository":"yourusername/your-repo",
  "trigger":"gui"
}

Limites de Taxa

A API tem um limite de 10 conversas simultâneas por conta. Se você precisar de um limite maior para seu caso de uso, entre em contato conosco em contact@all-hands.dev.

Se você exceder esse limite, a API retornará uma resposta 429 Too Many Requests.