> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /social-metadata

> Extraia metadados Open Graph, Twitter Card e gerais de qualquer URL pública.

## Endpoint

```
POST https://api.bunny.build/api/v1/social-metadata
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Busque e analise tags Open Graph, metadados Twitter Card e meta tags HTML padrão de qualquer URL pública. Retorna um objeto estruturado com título, descrição, imagem e propriedades de compartilhamento social, pronto para usar em componentes de pré-visualização de links, pipelines de ingestão de conteúdo ou ferramentas de auditoria de SEO.

## Casos de uso

* Renderizar pré-visualizações ricas de links em aplicativos de chat ou feeds sociais
* Auditar a completude do Open Graph em suas próprias páginas
* Ingerir metadados de artigos externos para ferramentas de curadoria de conteúdo
* Preencher pré-visualizações de compartilhamento quando usuários colam links

## Detalhes

A API busca a URL de destino no servidor e analisa as meta tags HTML. Páginas renderizadas por JavaScript podem retornar metadados incompletos. Redirecionamentos são seguidos automaticamente. URLs privadas ou protegidas por autenticação retornarão dados vazios ou parciais.

## Corpo da requisição

| Campo | Tipo   | Obrigatório | Descrição                             |
| ----- | ------ | ----------- | ------------------------------------- |
| `url` | string | Sim         | URL pública para extrair os metadados |

### Exemplo

```json theme={null}
{
  "url": "https://bunny.build"
}
```

## Resposta

### 200 OK

| Campo         | Tipo   | Descrição                                      |
| ------------- | ------ | ---------------------------------------------- |
| `url`         | string | URL resolvida (após redirecionamentos)         |
| `title`       | string | Título da página (OG ou `<title>`)             |
| `description` | string | Descrição da página                            |
| `image`       | string | URL da imagem OG ou Twitter                    |
| `site_name`   | string | Valor de `og:site_name`                        |
| `type`        | string | Valor de `og:type` (ex.: `website`, `article`) |

**Exemplo**

```json theme={null}
{
  "url": "https://bunny.build",
  "title": "Bunny — APIs for developers",
  "description": "Build faster with Bunny's ready-to-use API toolkit.",
  "image": "https://bunny.build/og.png",
  "site_name": "Bunny",
  "type": "website"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid or unreachable URL"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/social-metadata \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://bunny.build"}'
```