> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Módulo de API

O contrato público versionado, o plumbing de chaves e a superfície OpenAPI.

## Antes de começar

Abra seu projeto supastack baixado em Visual Studio Code usando Arquivo → Abrir pasta e escolha Terminal → Novo Terminal. A raiz do repositório é a pasta que contém package.json, apps e pacotes. Execute o comando abaixo e deixe seu terminal aberto. Se um comando não for reconhecido, conclua o guia de instalação da ferramenta antes de continuar.

Leia o tutorial da plataforma primeiro. Um servidor é o processo do aplicativo que responde às solicitações do navegador ou do telefone. A Web lê apps/web/.env.local, Expo lê apps/mobile/.env.local e os comandos de migração de banco de dados leem root .env. A demonstração sem banco de dados/painel é separada das contas reais/auth, que precisam migrar para Postgres. Uma finalização de compra somente por telefone ou desktop precisa de um back-end da Web executado separadamente.

[Instale as ferramentas e obtenha o código](https://supastack.dev/pt/docs/web/before-you-start.md)

[Aprenda comandos, arquivos e configuração](https://supastack.dev/pt/docs/web/terminal-basics.md)

[Conclua o tutorial inicial da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Instalação e configuração

O packages/api é a fonte de verdade para a superfície REST pública: schemas zod para pedidos, respostas e o envelope de erro, mais o documento OpenAPI (openApiDocument) servido em /api/v1/openapi. Os handlers de rota compõem estes schemas em vez de redefinir formas.

As chaves de API são emitidas por workspace com prefixo sk_<env>_, armazenadas com hash e comparação em tempo constante, e transportam scopes — leitura por predefinição. api-keys.ts possui criação, lookup e revogação.

```
apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi
```


## Fluxo de implementação

Adiciona endpoints dentro da versão existente: estende os schemas, mantém o envelope de erro e regenera a superfície OpenAPI para que /api/docs permaneça exato. As alterações breaking ganham uma nova versão, não uma mudança de forma silenciosa.

Resolve o workspace do chamador a partir da chave apresentada, aplica as mesmas regras de entitlement e validação da web app e faz rate-limit por chave.


## Verificação e resolução de problemas

Faz contract-test de cada forma de rota contra os schemas do package. Verifica que chaves desconhecidas, revogadas e pedidos com scope insuficiente falham todos com o envelope de erro documentado, e que o documento OpenAPI continua JSON válido.


## Seguinte

[Limitação de taxa](https://supastack.dev/pt/docs/modules/rate-limiting.md)