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

# Views API

> Salve e gerencie filtros e colunas das páginas de observabilidade por meio da Views API pública.

Use `/v3/views` para gerenciar as Views salvas usadas por [Traces](/docs/pt-BR/ai-studio/observability/traces.md) e [Logs](/docs/pt-BR/ai-studio/observability/logs.md). Uma View armazena um nome de exibição, uma página, uma string de filtro, colunas, rótulos de colunas opcionais e a visibilidade.

## Acesso

Autentique-se com uma chave de API de todo o workspace e conceda o domínio de permissão `view`. O acesso de leitura permite listar e recuperar Views compartilhadas; o acesso de gravação também permite criá-las, atualizá-las e excluí-las. Chaves de API com escopo de projeto não podem acessar as Views do workspace.

Views privadas exigem uma sessão de usuário. Somente os usuários listados em `private_for_ids` podem listar, recuperar, atualizar ou excluir uma View privada. Chaves de API podem acessar apenas Views compartilhadas e não podem criar Views privadas nem converter Views compartilhadas em privadas.

## Criar e recuperar uma View

Defina `display_name` e `page`. As páginas compatíveis são `traces` e `logs`. Nomes duplicados são permitidos.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://router.toqan.ai/eu/v3/views" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Customer investigations",
    "page": "traces",
    "columns": ["name", "attributes.customer.id"],
    "column_labels": {"attributes.customer.id": "Customer"}
  }'
```

As respostas de criação, recuperação e atualização envolvem o objeto salvo em `view`. Use o `view.id` retornado com `GET /v3/views/{view_id}`.

Defina `is_private: true` ao criar uma View com uma sessão de usuário para limitar o acesso a esse usuário. Defina `is_default: true` para tornar uma View a padrão da sua página e visibilidade: um padrão compartilhado substitui o padrão compartilhado anterior, enquanto um padrão privado substitui o padrão privado daquele usuário na mesma página.

## Listar Views

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://router.toqan.ai/eu/v3/views?page=traces&limit=25" \
  -H "Authorization: Bearer $TOQAN_API_KEY"
```

A resposta contém `data` e `has_more`. Defina `starting_after` como o `id` da última View retornada para obter a próxima página, ou `ending_before` como o `id` da primeira View retornada para obter a página anterior. Use um cursor por vez. O `limit` padrão é 10 e o máximo é 100. Omita `page` para listar todas as Views acessíveis.

## Atualizar e excluir uma View

Envie os campos alterados para `PATCH /v3/views/{view_id}`. Os campos escalares omitidos mantêm seus valores salvos. Ao definir `update_mask`, inclua todos os campos a serem alterados; os campos fora da máscara mantêm seus valores salvos. Para limpar todas as colunas ou rótulos de colunas, inclua seus caminhos na máscara. O Protobuf JSON codifica a máscara como uma string separada por vírgulas.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://router.toqan.ai/eu/v3/views/$VIEW_ID" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "",
    "columns": [],
    "column_labels": {},
    "update_mask": "description,columns,columnLabels"
  }'
```

Exclua uma View com `DELETE /v3/views/{view_id}`. Uma exclusão bem-sucedida retorna um objeto JSON vazio. Views inexistentes, Views de outro workspace e Views privadas fora do acesso do chamador retornam `404`.

Consulte a [referência da Views API](/docs/pt-BR/reference/views/list-saved-views.md) para ver todos os campos de solicitação e resposta. Substitua as chamadas legadas a `/v2/views` e `/v2/workspaces/views` por `/v3/views` e pelos formatos de resposta acima.


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