# KOS Agência - documentação de APIs

Site: https://www.kosagencia.com
Catálogo machine-readable: https://www.kosagencia.com/.well-known/api-catalog
Especificação OpenAPI: https://www.kosagencia.com/openapi.json
Hub HTML para desenvolvedores: https://www.kosagencia.com/docs
Alias: https://www.kosagencia.com/developers

## Visão geral

API HTTP da KOS Agência (kosagencia.com). A operação pública para function calling é `submitContactLead` (POST /api/contact).
Erros da API retornam JSON `{ ok: false, error, errorCode, hint }`.
Endpoints protegidos exigem `Authorization: Bearer <secret>`.

## POST /api/contact

operationId: `submitContactLead`. Envia um lead do formulário de contato do site.

- **Autenticação:** nenhuma (protegido por reCAPTCHA, rate limit e honeypot).
- **Content-Type:** `application/json`
- **Resposta de sucesso:** `200` com `{ "ok": true, "requestId": "..." }`

### Campos obrigatórios

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `firstName` | string | Nome |
| `lastName` | string | Sobrenome |
| `email` | string | E-mail válido |
| `phone` | string | Telefone (min. 8 dígitos) |

### Campos opcionais

`company`, `message`, `pagePath`, `pageUrl`, `referrer`, `utm`, `recaptchaToken`, `recaptchaAction`, `formStartedAtMs`, `locale`.

## GET /api/blog/posts

Lista posts do blog (resumo para reconciliação).

- **Autenticação:** `Authorization: Bearer <BLOG_INGEST_SECRET>`
- **Resposta:** `{ "count": number, "posts": [{ "slug", "title", "isoDate", "updatedAt" }] }`

## POST /api/blog/posts

Cria ou atualiza um ou mais posts (upsert por `slug`).

- **Autenticação:** `Authorization: Bearer <BLOG_INGEST_SECRET>`
- **Corpo:** um post ou `{ "posts": [...] }`

## GET /api/blog/posts/:slug

Retorna o post completo.

- **Autenticação:** `Authorization: Bearer <BLOG_INGEST_SECRET>`

## DELETE /api/blog/posts/:slug

Remove um post do disco (posts seed embutidos não são removiveis).

- **Autenticação:** `Authorization: Bearer <BLOG_INGEST_SECRET>`

## Recursos para agentes

- Hub HTML: https://www.kosagencia.com/docs
- OpenAPI: https://www.kosagencia.com/openapi.json
- Contexto oficial (LLM): https://www.kosagencia.com/llms.txt
- Contexto estendido: https://www.kosagencia.com/llms-full.txt
- Feed RSS: https://www.kosagencia.com/rss.xml
- Sitemap: https://www.kosagencia.com/sitemap.xml