Referência da API

A API pública está disponível em https://api.ara.so/v3. Uma chave de API ara_ está vinculada ao workspace do Ara onde foi criada.

Obter uma chave de API

1. Entre no Ara e abra seu workspace.
2. Abra Configurações → Ara CLI.
3. Em Chaves de API para CI, selecione Gerar chave.
4. Escolha os escopos mais restritos e uma data de expiração, depois copie a chave.

Verificar a chave

Defina a chave no seu shell e chame /v3/self:

$
export ARA_API_KEY="ara_..."
$
$
curl https://api.ara.so/v3/self \
>
  -H "Authorization: Bearer $ARA_API_KEY"

A resposta inclui o ID da organização vinculado à chave:

1
{
2
  "principal_type": "service_user",
3
  "service_user_id": "key_3f9a",
4
  "service_user_name": "ci-bot",
5
  "org_id": "org_8c2d1e"
6
}

Use esse valor nos exemplos restantes:

$
export ARA_ORG_ID="org_8c2d1e"

Experimentar a API

Listar repositórios conectados

Requer repos:read.

$
curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/repositories" \
>
  -H "Authorization: Bearer $ARA_API_KEY"

Iniciar uma sessão

Requer run. Substitua acme/web por um repositório conectado ao workspace.

$
curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions" \
>
  -H "Authorization: Bearer $ARA_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "repo": "acme/web",
>
    "prompt": "Fix the flaky auth test, add a regression case, and open a PR."
>
  }'

A resposta inclui um session_id. A criação de sessão é assíncrona.

Ler a sessão

Requer sessions:read.

$
export ARA_SESSION_ID="ses_91af3c"
$
$
curl "https://api.ara.so/v3/organizations/$ARA_ORG_ID/sessions/$ARA_SESSION_ID" \
>
  -H "Authorization: Bearer $ARA_API_KEY"

Escopos comuns

Para campos de requisição exatos, esquemas de resposta e todos os endpoints públicos, abra a referência completa de endpoints.

Erros