# info.summary
Public contact lead capture and authenticated blog CMS for kosagencia.com.

# info.description
HTTP API for KOS Agência (kosagencia.com), a Brazilian brand-management agency. The public, function-calling-friendly operation is `submitContactLead`. Blog ingest endpoints require `Authorization: Bearer <BLOG_INGEST_SECRET>` and are not for end-user agents. Human docs: https://www.kosagencia.com/docs — Markdown API notes: https://www.kosagencia.com/docs/api — Catalog: https://www.kosagencia.com/.well-known/api-catalog.

# tags[].description
Public lead capture from the website contact form.

# tags[].description
Authenticated editorial ingest used by the sibling KOS_BlogAutoPost project.

# tags[].description
First-party beacons and WhatsApp click redirect. Not a product API.

# paths./api/contact.post.description
Create a commercial lead for KOS Agência. Use this when a person wants branding, brand management, positioning, or an integrated strategy+production conversation. Protected by optional reCAPTCHA v3, honeypot, and per-IP/per-email rate limits. No API key required.

# paths./api/contact.post.requestBody.content.application/json.example.message
Queremos reposicionar a marca para 2027.

# paths./api/contact.post.responses.200.description
Lead accepted for delivery (email + CRM).

# paths./api/contact.get.description
Lightweight discovery ping. When CONTACT_API_SECRET is configured, send `Authorization: Bearer <secret>`.

# paths./api/blog/posts.get.description
Returns a short inventory of stored posts for reconciliation. Requires BLOG_INGEST_SECRET.

# paths./api/blog/posts.post.description
Upsert one post or a batch keyed by `slug`. Requires BLOG_INGEST_SECRET. Used by the editorial CMS, not by public agents.

# paths./api/blog/posts.post.responses.200.description
Upsert result (partial success possible).

# paths./api/blog/posts/{slug}.get.description
Returns the stored post document. Requires BLOG_INGEST_SECRET.

# paths./api/blog/posts/{slug}.delete.description
Removes a disk-backed post. Requires BLOG_INGEST_SECRET.

# paths./api/wa.get.description
First-party redirect that records a WhatsApp click server-side and then 302s to the official WhatsApp thread. Do not use this as a messaging API.

# paths./api/wa.get.parameters[].description
Stable trackingRef (alphanumeric, max 40).

# paths./api/track.post.description
Same-origin beacon used as a second path for WhatsApp click attribution. Always returns 200 (best-effort).

# paths./api/collect.post.description
Same-origin batch of pageview/engagement events forwarded to the CRM. Always returns 200 (best-effort).

# components.securitySchemes.blogIngestBearer.description
Shared secret with the KOS_BlogAutoPost CMS (AGENCIA_CMS_SECRET).

# components.securitySchemes.contactBearer.description
Optional secret for GET /api/contact status.

# components.schemas.ApiError.properties.error.description
Human-readable error message. Localized for contact form errors.

# components.schemas.ApiError.properties.errorCode.description
Stable machine-readable code for function calling and retries.

# components.schemas.ApiError.properties.hint.description
How an agent should recover: docs URL, required fields, or next action.