> ## 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

> Extract Open Graph, Twitter Card, and general metadata from any public URL.

## Endpoint

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

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Fetch and parse Open Graph tags, Twitter Card metadata, and standard HTML meta tags from any public URL. Returns a structured object with title, description, image, and social-sharing properties, ready to use in link preview components, content ingestion pipelines, or SEO auditing tools.

## Use cases

* Render rich link previews in chat apps or social feeds
* Audit Open Graph completeness across your own pages
* Ingest external article metadata for content curation tools
* Populate sharing previews when users paste links

## Details

The API fetches the target URL server-side and parses HTML meta tags. JavaScript-rendered pages may return incomplete metadata. Redirects are followed automatically. Private or auth-gated URLs will return empty or partial data.

## Request body

| Field | Type   | Required | Description                         |
| ----- | ------ | -------- | ----------------------------------- |
| `url` | string | Yes      | Public URL to extract metadata from |

### Example

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

## Response

### 200 OK

| Field           | Type         | Description                                                          |
| --------------- | ------------ | -------------------------------------------------------------------- |
| `url`           | string       | The URL that was fetched                                             |
| `title`         | string\|null | Page title (`og:title` or `<title>`)                                 |
| `description`   | string\|null | Page description (`og:description` or `<meta name="description">`)   |
| `image`         | string\|null | OG image URL                                                         |
| `site_name`     | string\|null | `og:site_name` value                                                 |
| `favicon`       | string\|null | Favicon URL (discovered from `<link rel="icon">`, or `/favicon.ico`) |
| `twitter`       | object       | Twitter Card metadata                                                |
| `twitter.card`  | string\|null | `twitter:card` value (e.g. `summary_large_image`)                    |
| `twitter.title` | string\|null | `twitter:title` value                                                |

**Example**

```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",
  "favicon": "https://bunny.build/favicon.ico",
  "twitter": {
    "card": "summary_large_image",
    "title": "Bunny — APIs for developers"
  }
}
```

### 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."
}
```

## cURL example

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