# API v1

API de distribuição pública. As versões mantidas pelo projeto continuam estáticas; o catálogo também inclui publicações por usuário. Para autenticação e publicação, consulte [PUBLISHING.md](PUBLISHING.md). Respostas JSON UTF-8, sem autenticação. `schema_version: 1` identifica os documentos de catálogo e índice. A URL-base é a raiz da instalação, inclusive eventual subdiretório.

## Endpoints

| Caminho relativo à base | Resposta |
| --- | --- |
| `api/v1/catalog.json` | `schema_version`, `name`, `total`, `skills[]` |
| `api/v1/categories.json` | `schema_version`, `categories[]` com `id` e `name` |
| `api/v1/skills/{id}/index.json` | `schema_version`, `id`, `latest`, `versions[]` |
| `api/v1/skills/{id}/versions/{version}/manifest.json` | Metadados e integridade do pacote |
| `api/v1/skills/{id}/versions/{version}/SKILL.md` | Instruções Markdown |
| `api/v1/skills/{id}/versions/{version}/download.zip` | Pacote ZIP contendo a pasta `{id}/` |

GET e HEAD são suficientes. Caminhos inexistentes retornam HTTP 404; o corpo de erro depende da hospedagem e não deve ser interpretado como JSON. Os endpoints desta tabela são de leitura. A autenticação e as operações de escrita usam endpoints separados, documentados em PUBLISHING.md. Clientes filtram `skills[]` por categoria, tags e compatibilidade. Parâmetros de consulta não são filtros.

## Metadados e URLs

Consulte `schemas/skill.schema.json` para os campos de autoria. A versão aceita o subconjunto estável `MAJOR.MINOR.PATCH`, sem prefixo `v`, zeros iniciais, prereleases ou build metadata. Ordenação é numérica.

O manifesto acrescenta `published_at` (UTC ISO 8601), `sha256` (hexadecimal), `size` (bytes do ZIP), `archive` (`download.zip`), `entrypoint` (`{id}/SKILL.md`) e `format` (`agent-skills`). `published_at` registra a criação local do snapshot, não a data em que o domínio ficou acessível.

Catálogo e índice acrescentam:

- `status`: `active` ou `withdrawn`.
- `withdrawal_reason`: motivo da retirada, ou `null`.
- `manifest_url`, `download_url`, `skill_url`: relativos à raiz da instalação.
- No catálogo: `page_url`, `index_url`, `versions_count` e `latest`.

Exemplo de resolução: base `https://exemplo.org/catalogo/` + `api/v1/catalog.json`. Sempre mantenha a barra final da base. Resolva `archive` relativamente à URL do manifesto; `entrypoint` é um caminho interno do ZIP.

## Versões e retiradas

`latest` é a maior versão numérica ativa, ou `null` se todas estiverem retiradas. O catálogo tem uma entrada por identificador; se não houver versão ativa, a entrada descreve a versão mais alta retirada. O site oculta essas entradas da busca, mas mantém páginas e histórico.

Antes de instalar, consulte o índice e verifique o estado da versão escolhida. Retiradas não modificam o manifesto ou ZIP históricos. Pacotes retirados continuam acessíveis para auditoria; não representam recomendação de uso. Status pode ser atualizado independentemente do pacote.

`release` impede sobrescritas locais de uma versão. A preservação entre publicações também exige manter `releases/` no repositório e proibir alteração de snapshots já aprovados na revisão.

## Integridade e instalação

Valide o SHA-256 e tamanho do ZIP. Um checksum distribuído pela mesma origem detecta corrupção; não autentica o autor se a origem for comprometida. O instalador aceita `--sha256` de outro canal e só permite HTTPS fora de loopback.

O instalador recusa caminhos fora da pasta da skill, symlinks, nomes duplicados sem distinção de caixa, arquivos ocultos, pacotes acima de 24 MiB descompactados e destinos existentes. Limite de criação do catálogo: 20 MiB de arquivos por skill. Não executa scripts. Arquivos são instalados sem preservar o bit executável; use o interpretador indicado pela skill quando necessário.

## Hospedagem

Configure CORS `Access-Control-Allow-Origin: *` na API, JSON `application/json`, Markdown `text/markdown` e ZIP `application/zip`. Use cache curto para catálogo/índices e cache imutável para URLs versionadas. O servidor de desenvolvimento demonstra esses cabeçalhos. A hospedagem precisa aplicar as regras equivalentes descritas em `DEPLOYMENT.md`.