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

# Quickstart

> Liste seus agentes, envie uma mensagem, leia a resposta. Cinco minutos do zero a uma integração funcionando.

Este walkthrough leva você de uma API key nova até um round-trip de chat funcionando em cinco minutos.

## 0. Pré-requisitos

* Um workspace com pelo menos um agente **publicado** (use o Studio para criar um se você não tiver nenhum).
* Uma API key de workspace (veja [Autenticação](/pt/api-reference/authentication)).

Exporte a key uma vez para os snippets ficarem copy-paste:

```bash theme={null}
export GENNIA_API_KEY="gsk_sua_key_aqui"
```

## 1. Verificar a key

O endpoint `health` valida a key e retorna o workspace ao qual ela está vinculada.

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/health" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

```json Resposta theme={null}
{
  "status": "ok",
  "workspacePublicId": "9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21",
  "apiKeyPublicId": "7f2b1c44-6e90-4d2a-83b5-c1f2d3a4b5c6"
}
```

Uma resposta diferente de `ok` — ou qualquer `401` — significa **pare**. Revise [Autenticação](/pt/api-reference/authentication) antes de continuar.

## 2. Listar seus agentes

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents" \
  -H "X-Api-Key: $GENNIA_API_KEY"
```

A resposta é paginada. Guarde o `publicId` de um agente com `status: "published"` — você vai precisar a seguir.

```json Resposta (resumida) theme={null}
{
  "items": [
    {
      "publicId": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Bot de Suporte",
      "status": "published",
      "description": "Responde dúvidas sobre cobrança e acesso à conta."
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}
```

## 3. Enviar uma mensagem

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Oi, pode resumir o status da minha conta?",
    "externalUserId": "user_42"
  }'
```

O endpoint bloqueia até o agente terminar (ou `timeoutSeconds` estourar — default é 60s). A resposta contém o texto da reply, o ID da conversa, o uso de tokens e o custo.

```json Resposta (resumida) theme={null}
{
  "conversationId": "9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21",
  "messages": [
    {
      "role": "assistant",
      "content": "Sua conta está ativa e você tem 4.500 créditos restantes…"
    }
  ],
  "usage": {
    "inputTokens": 245,
    "outputTokens": 89,
    "totalCost": 0.0023
  }
}
```

## 4. Continuar a conversa

Passe de volta o `conversationId` do passo 3 para manter o mesmo thread:

```bash theme={null}
curl "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"E sobre a próxima renovação?\",
    \"conversationId\": \"$CONVERSATION_ID\"
  }"
```

## 5. Respostas em streaming

Para UIs interativas, use o endpoint SSE em vez do bloqueante. Mesmo body shape; resposta é `text/event-stream`.

```bash theme={null}
curl -N "https://api.gennia.ai/public/api/v1/agents/$AGENT_ID/messages/stream" \
  -H "X-Api-Key: $GENNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Me conta uma história longa"}'
```

Você recebe uma stream de eventos: `conversation-id`, vários `text-delta`, e por fim `debug-info` com uso de tokens e custo.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Convenções" icon="list-check" href="/pt/api-reference/conventions/pagination">
    Paginação, formato de erros, headers comuns.
  </Card>

  <Card title="Referência completa" icon="book" href="/pt/api-reference/introduction">
    Cada endpoint com try-it-out e schemas. Navegue em "Endpoints" no menu lateral.
  </Card>
</CardGroup>