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

# Introdução à API

> Visão geral da API pública do Triglit

A **API Pública do Triglit** é uma API RESTful que permite criar e gerenciar workflows, versões e triggers diretamente nos seus produtos. A API está disponível em:

```
https://api.triglit.com/v1/gateway
```

## Características

* ✅ **RESTful**: Segue padrões REST
* ✅ **Versionada**: Versão atual: `v1`
* ✅ **Autenticada**: Via chaves de API
* ✅ **Documentada**: OpenAPI 3.0
* ✅ **Idempotente**: Quando aplicável
* ✅ **Observável**: Logs e métricas completas

## Base URL

Todas as requisições devem ser feitas para:

```
https://api.triglit.com/v1/gateway
```

## Autenticação

A API usa **chaves de API** para autenticação. Veja a [documentação de autenticação](/authentication) para detalhes.

**Header obrigatório:**

```
X-API-Key: pk_sua_chave_aqui
```

## Formatos

### Request

* **Content-Type**: `application/json`
* **Accept**: `application/json`

### Response

* **Content-Type**: `application/json`
* **Encoding**: UTF-8

## Versionamento

A API é versionada via URL:

```
/v1/gateway/workflows  # Versão 1
/v2/gateway/workflows  # Versão 2 (futuro)
```

**Política de versionamento:**

* Versões antigas são mantidas por pelo menos 12 meses
* Breaking changes apenas em novas versões
* Deprecation warnings com 6 meses de antecedência

## Rate Limiting

### Chave Pública (pk\_)

* **Limite**: 100 requisições/minuto
* **Burst**: 20 requisições simultâneas

### Chave Secreta (sk\_)

* **Limite**: 1000 requisições/minuto
* **Burst**: 100 requisições simultâneas

### Headers de Rate Limit

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

## Paginação

Endpoints de listagem usam paginação:

### Query Parameters

* **`limit`**: Número de itens por página (padrão: 20, máximo: 100)
* **`offset`**: Número de itens para pular (padrão: 0)
* **`page`**: Número da página (0-indexed, padrão: 0)

### Response

```json theme={null}
{
  "items": [...],
  "total": 150,
  "limit": 20,
  "offset": 0,
  "hasMore": true
}
```

## Ordenação

Alguns endpoints suportam ordenação:

```
GET /workflows?sortBy=createdAt&sortOrder=desc
```

**Parâmetros:**

* **`sortBy`**: Campo para ordenar
* **`sortOrder`**: `asc` ou `desc`

## Filtros

Endpoints de listagem suportam filtros:

```
GET /workflows?isActive=true&search=pedido
```

## Respostas de Erro

### Formato Padrão

```json theme={null}
{
  "statusCode": 400,
  "message": "Descrição do erro",
  "error": "Bad Request",
  "timestamp": "2024-01-15T10:00:00Z",
  "path": "/v1/gateway/workflows"
}
```

### Códigos de Status

* **200 OK**: Sucesso
* **201 Created**: Recurso criado
* **400 Bad Request**: Requisição inválida
* **401 Unauthorized**: Autenticação falhou
* **403 Forbidden**: Sem permissão
* **404 Not Found**: Recurso não encontrado
* **409 Conflict**: Conflito (ex: duplicado)
* **429 Too Many Requests**: Rate limit excedido
* **500 Internal Server Error**: Erro do servidor

## Idempotência

Alguns endpoints são idempotentes usando **idempotency keys**:

```bash theme={null}
POST /v1/gateway/workflows
X-Idempotency-Key: unique-key-123
{
  "name": "Meu Workflow"
}
```

**Endpoints idempotentes:**

* `POST /workflows`
* `POST /workflow-versions`
* `POST /triggers`

## Webhooks

O Triglit pode enviar webhooks para seus endpoints:

<Card title="Guia de Webhooks" icon="plug" href="/guides/webhooks">
  Aprenda a configurar e receber webhooks
</Card>

## Endpoints Disponíveis

A API pública fornece endpoints para:

* **Workflows**: Criar, listar, obter e gerenciar workflows
* **Workflow Versions**: Criar, listar, obter, atualizar, deletar e publicar versões de workflows
* **Triggers**: Criar e gerenciar triggers para iniciar workflows
* **Sub-Tenants**: Criar e gerenciar sub-tenants para segmentação

## OpenAPI Specification

A especificação OpenAPI está disponível:

<Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
  Baixe a especificação OpenAPI 3.0
</Card>

## SDKs e Bibliotecas

O Triglit oferece um **SDK oficial** para JavaScript/TypeScript:

### Instalação

```bash theme={null}
npm install triglit
```

### Uso Básico

```javascript theme={null}
import Triglit from 'triglit';

const client = new Triglit({ apiKey: 'pk_sua_chave_aqui' });

// Listar workflows
const workflows = await client.workflows.list();

// Criar trigger
const trigger = await client.triggers.create({
  workflowVersionId: 'version_id',
  type: 'webhook',
  config: { path: '/webhook' },
  isActive: true
});
```

Para mais informações sobre os métodos disponíveis, consulte a [documentação do SDK](https://github.com/Triglit/typescript-sdk/blob/HEAD/api.md).

## Suporte

* **Documentação**: Esta documentação
* **Email**: [support@triglit.com](mailto:support@triglit.com)
* **Status**: [status.triglit.com](https://status.triglit.com)

<Tip>
  Use a especificação OpenAPI para gerar clientes automaticamente em sua linguagem preferida.
</Tip>