API Reference

URL Metadata Extractor

Fetch and extract Open Graph, Twitter Card, and meta tag data from any URL

Extract Open Graph tags, Twitter Card data, page titles, descriptions, and favicons from any URL with a single API call. URL metadata extraction powers link preview cards in chat apps, social sharing features, content aggregation platforms, and SEO auditing tools that need structured page information at scale.

Open GraphTwitter Cardsmeta tagsfavicon extraction

Endpoint

POST /v1/url/metadata

Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.

Open Swagger UI (interactive docs)

Request

{
  "url": "https://example.com/article"
}

Request Fields

Field	Type	Description
`url`	`string`	Target URL

Response

{
  "url": "https://example.com/article",
  "title": "Example Article",
  "description": "An interesting article about examples",
  "image": "https://example.com/og-image.jpg",
  "siteName": "Example",
  "type": "article",
  "twitterCard": "summary_large_image"
}

Response Fields

Field	Type	Description
`url`	`string`	Target URL
`title`	`string`	Field value
`description`	`string`	Field value
`image`	`string`	Field value
`siteName`	`string`	Field value
`type`	`string`	Field value
`twitterCard`	`string`	Field value

Error Codes

Status	Meaning
`200`	Request completed successfully
`400`	Bad request — invalid or missing parameters
`401`	Missing or invalid `X-API-Key` header
`429`	Rate limit exceeded — check `Retry-After` header
`500`	Internal server error

Common Error Scenarios

400 Invalid URL

Request that triggers this:

{"url": "definitely not a url"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid URL", "status": 400, "detail": "'definitely not a url' is not a valid URL"}

How to fix: Use a valid HTTP or HTTPS URL. Ensure the URL is properly formatted with protocol (e.g., https://example.com).

404 Page not found

Request that triggers this:

{"url": "https://example.com/nonexistent"}

Error response:

{"type": "/problems/not-found", "title": "Page Not Found", "status": 404, "detail": "The URL returned HTTP 404"}

How to fix: Verify that the URL is correct and the page exists. Update the URL to point to an existing resource.

Code Examples

curl -X POST /v1/url/metadata \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "url": "https://example.com/article"
}'

// Node.js (18+) or modern browser
const response = await fetch("/v1/url/metadata", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/article"
}),
});

const data = await response.json();
console.log(response.status, data);

import requests

response = requests.post(
    "/v1/url/metadata",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "url": "https://example.com/article"
},
)

print(response.status_code)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "url": "https://example.com/article"
}`)
	req, _ := http.NewRequest("POST", "/v1/url/metadata", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}

{
  "name": "url_metadata",
  "description": "Fetch and extract Open Graph, Twitter Card, and meta tag data from any URL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/url/metadata",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference