# Catbox: instruções para agentes Hermes e OpenClaw

Serviço público de hospedagem de arquivos, sem autenticação.

**Base URL:** `https://ipe.srv2001213.hstgr.cloud`

## Enviar arquivo

Use `POST /upload` (ou `POST /api/upload`) com `multipart/form-data` e campo **file** contendo o arquivo binário.

```bash
curl -fsS -X POST 'https://ipe.srv2001213.hstgr.cloud/upload' \
  -F 'file=@/caminho/relatorio.pdf'
```

Exemplo de resposta:

```json
{
  "success": true,
  "url": "https://ipe.srv2001213.hstgr.cloud/f/aB12.pdf",
  "id": "aB12.pdf",
  "filename": "relatorio.pdf",
  "size": 12345,
  "sha256": "<hash SHA-256 calculado pelo servidor>"
}
```

O nome público contém **4 caracteres aleatórios** (letras e números) e a extensão original, quando válida. O nome original é preservado apenas nos metadados da resposta.

## Verificar a validade do link sem baixar o arquivo

Envie **HEAD** para a URL exata retornada no campo `url`:

```bash
curl -sS -I 'https://ipe.srv2001213.hstgr.cloud/f/aB12.pdf'
```

Para consultar somente o código HTTP:

```bash
curl -sS -o /dev/null -w '%{http_code}\n' -I 'https://ipe.srv2001213.hstgr.cloud/f/aB12.pdf'
```

- **200:** o arquivo está disponível no servidor naquele instante.
- **404:** o arquivo não foi encontrado.
- **429:** limite de requisições de upload atingido (aplica-se aos uploads, não à consulta HEAD).
- **5xx:** erro no servidor ou indisponibilidade; tente novamente mais tarde.

`HEAD` devolve cabeçalhos como `Content-Length`, `Content-Type` e `Last-Modified`, **sem transferir o corpo do arquivo**. Um status 200 comprova disponibilidade atual, não garante disponibilidade futura nem integridade ponta a ponta. Para verificar conteúdo, compare o SHA-256 retornado no upload com o hash do arquivo local.

## Orientações de uso para agentes

1. Envie apenas arquivos autorizados para compartilhamento público; **qualquer pessoa com a URL pode acessar o conteúdo**.
2. Aguarde a resposta de sucesso do upload e armazene a URL retornada.
3. Antes de entregar o link ao destinatário, faça `HEAD` na URL e confirme HTTP 200.
4. Compartilhe a URL **exata** retornada pela API. Não tente adivinhar ou reconstruir nomes.
5. Em caso de erro 429, aguarde e repita com moderação. Evite uploads paralelos excessivos.

**Limites atuais:** 200 MB por arquivo, 5 uploads por minuto por IP e 2 uploads simultâneos. Armazenamento sem expiração automática prevista, sujeito à disponibilidade e à capacidade do servidor.

## Endpoints

- `POST /upload`: upload de arquivo.
- `POST /api/upload`: alias do upload.
- `GET /f/{id}`: obter o arquivo.
- `HEAD /f/{id}`: verificar disponibilidade sem download.
- `GET /health`: verificar saúde do serviço.
- `GET /openapi.json`: especificação OpenAPI.
- `GET /AGENTES.md`: este guia Markdown.

