> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeiros passos

> Configure uma chave e use cURL para obter uma cotação, executar uma ferramenta e recuperar o resultado.

## Visão geral

Este exemplo usa `web_search` para preparar a chave, obter uma cotação gratuita, executar e recuperar o resultado. Basta um shell compatível com Bash e cURL, sem SDK específico.

## Pré-requisitos

Prepare estes cinco itens:

* Uma conta NoimosAI com acesso à [Developer Platform](https://platform.noimosai.com)
* Um projeto Developer Platform com acesso API habilitado
* Uma chave de desenvolvedor com prefixo `nmp_` e permissões necessárias
* Um shell compatível com Bash
* cURL, jq e uuidgen

Para execução paga, verifique também saldo pré-pago em USD e limites mensais do projeto. Veja permissões em [Autenticar solicitações](https://docs.noimosai.com/pt/developers/api/authentication.md).

Se nenhum projeto acessível aparecer, peça a um `OWNER` ou `ADMIN` da organização para criar um ou adicionar você. Crie chaves dentro de um projeto do qual participa.

## Executar a API

Siga estas sete etapas para a primeira execução.

### 1. Criar uma chave na Developer Platform

Um `ADMIN` ou `DEVELOPER` do projeto pode criar uma chave na [Developer Platform](https://platform.noimosai.com):

1. Entre e selecione o projeto.
2. Abra **Chaves API** e escolha **Criar nova chave**.
3. Defina nome descritivo, validade e permissões, e crie a chave.
4. Guarde a chave secreta com segurança: ela aparece uma única vez.

Este guia exige `project:read`, `tools:read`, `tools:execute` e `executions:read`. Para outros usos, conceda apenas as permissões necessárias.

### 2. Definir chave e URL base

Use variáveis de ambiente para chave e URL base, evitando segredos diretamente no histórico de comandos ou código-fonte.

```bash theme={null}
export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."
```

> [!WARNING]
>
> A chave só aparece na criação. Não a salve em Git, documentos compartilhados ou JavaScript do cliente.

### 3. Verificar o projeto da chave

Primeiro confirme que a chave corresponde ao projeto esperado da Developer Platform.

```bash theme={null}
curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"
```

A resposta inclui ID da organização, ID e nome do projeto em `data`. Se não for o projeto esperado, verifique a chave antes de executar trabalho pago.

```json theme={null}
{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}
```

### 4. Consultar ferramentas disponíveis

Obtenha nomes, descrições, esquemas, exemplos, disponibilidade e preços atuais.

```bash theme={null}
NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq
```

Verifique `executionEnabled` na resposta geral e `available` na ferramenta. Use a resposta como referência atual sem assumir quantidades, modelos, esquemas ou preços fixos.

Filtre a resposta salva para consultar apenas `web_search`.

```bash theme={null}
echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'
```

### 5. Obter uma cotação antes de executar

Envie nome da ferramenta e argumentos para receber versão de preços e reserva máxima. Isso não inicia trabalho pago.

```bash theme={null}
NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq
```

A cotação retorna `priceVersion` e `maximumChargeMicros` para execução. Reutilize os valores sem alterar ou calcular. `maximumChargeMicros` é um inteiro em milionésimos de USD: 1 USD equivale a 1,000,000 micros.

```json theme={null}
{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}
```

Os valores acima apenas ilustram o formato. A próxima etapa lê os valores reais da resposta salva.

### 6. Executar a solicitação cotada

Mantenha ferramenta e argumentos da cotação, adicionando versão de preços e reserva máxima recebidas. Inclua uma chave de idempotência para identificar a solicitação lógica.

```bash theme={null}
export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')
```

O exemplo reutiliza a cotação da etapa 5 e gera uma chave com `uuidgen`. A aceitação retorna HTTP 202 e um ID de execução.

```json theme={null}
{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}
```

A resposta também inclui versão de preços, saída, erros e datas. `chargedMicros: 0` durante o processamento não significa que a cobrança final seja gratuita.

### 7. Consultar o mesmo ID de execução

Use o ID salvo na etapa 6 e consulte a intervalos de pelo menos cinco segundos até concluir.

```bash theme={null}
while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done
```

`queued`, `running` e `waiting` indicam processamento em andamento. Em `succeeded`, leia `output` e `chargedMicros`. Veja outros estados em [Gerenciar execução e cobrança](https://docs.noimosai.com/pt/developers/api/execution-and-billing.md).

> [!WARNING]
>
> Se a resposta for desconhecida, não reenvie com outra chave de idempotência. O mesmo corpo e a mesma chave recuperam a execução já aceita.

## Páginas relacionadas

Depois, consulte as páginas pertinentes:

* [Autenticar solicitações](https://docs.noimosai.com/pt/developers/api/authentication.md): permissões e armazenamento das chaves
* [Gerenciar execução e cobrança](https://docs.noimosai.com/pt/developers/api/execution-and-billing.md): processos longos, novas tentativas e cobrança
* [Referência da API](https://docs.noimosai.com/pt/developers/api/reference.md): endpoints, estados e limites
* [Documentação](https://platform.noimosai.com/docs) Developer Platform: exemplos atuais


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.