Name: Open Graph & Twitter Card Validator API
Brand: glowhalo
SKU: api-glowhalo-open-graph-validator-api
Availability: InStock
Author: API Market

# Open Graph & Twitter Card Validator API

## Overview

This is a validator, not a scraper. The Open Graph & Twitter Card Validator API checks the social-sharing tags of a page and tells you what is wrong with them. Give it a page URL (or HTML) and get one graded JSON report on the required and recommended Open Graph properties, the Twitter/X card type and image, title and description lengths, og:url versus canonical mismatches and, by default, one small ranged request to the image to confirm it responds, has an image content type and a size within platform limits. It also returns a best-guess `preview` object, which is not a reproduction of what any platform crawler sees.

It is built for CI gates, SEO audits and publishing tools that need a headless social-tag check. This API is not affiliated with Meta, Facebook, X or LinkedIn.

## Features

*   **2 endpoints**: Check a live URL, or validate HTML you supply (offline, no image request).
*   **Open Graph and Twitter Card rules**: Required and recommended tags, valid `twitter:card` values, relative or non-HTTPS image URLs, duplicate tags and canonical mismatches.
*   **Image check**: One 1-byte ranged request to og:image (or twitter:image) for response, content type and size; skip it with `probe=0`.
*   **Coded findings**: Stable `code` values with a severity (error, warning or info) and a message.
*   **Grade and score**: A+ to F and a score out of 100 (one error scores 75).
*   **Best-guess preview**: Open Graph first, then Twitter, then the page's own tags.
*   **Caching**: URL checks are cached for 6 hours; `fresh=1` bypasses the cache.

## Use Cases

*   **CI and release gates**: Fail a build when a page loses its og:image or uses an invalid Twitter card type.
*   **SEO audits**: Check a list of URLs for missing titles, descriptions and oversized or unreachable images.
*   **Publishing tools**: Validate the HTML a CMS template generates before a post goes live.
*   **Monitoring**: Re-check key landing pages on a schedule and alert when the grade drops.
*   **Agencies**: Produce a quick social-tag report per client page.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/glowhalo/open-graph-validator-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate the social tags of a URL

Fetches the page (up to 5 redirects, first 1 MB of HTML), reads its Open Graph, Twitter Card and basic meta tags and judges them. Unless `probe=0`, it also makes one small ranged request to the image (og:image, falling back to twitter:image) to check that it responds, reports an image content type and has a size within platform limits. Results are cached for 6 hours per URL.

**Method:** `GET`

**Endpoint:** `/v1/check`

**Parameters:**

| Name | In | Description | Type | Required |
|---|---|---|---|---|
| `url` | query | Page to inspect. A value without a scheme is treated as https. The aliases `u`, `uri`, `link`, `target`, `site`, `website`, `domain` and `host` are also accepted. | string | Yes |
| `probe` | query | Set to `0` to skip the og:image request. | string | No |
| `fresh` | query | Set to `1` to bypass the 6-hour cache. | string | No |

**Example Request:**

```bash
curl -s "https://prod.api.market/api/v1/glowhalo/open-graph-validator-api/v1/check?url=https://example.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (abridged):**

```json
{
  "found": true,
  "grade": "B",
  "score": 80,
  "summary": { "errors": 0, "warnings": 2, "infos": 1 },
  "issues": [
    { "severity": "warning", "code": "twitter_card_missing", "message": "..." }
  ],
  "preview": { "title": "...", "description": "...", "image": "https://..." },
  "imageCheck": { "status": 200, "contentType": "image/png", "sizeBytes": 123456 },
  "cached": false
}
```

#### 2. Validate HTML you send in

Runs the same tag checks on HTML in the request body. Offline: no outbound request is made and the image is not requested. Maximum 512 KB.

**Method:** `POST`

**Endpoint:** `/v1/validate`

**Body:** JSON with `html` (required) and `url` (optional, used only to resolve relative URLs).

**Example Request:**

```bash
curl -s -X POST "https://prod.api.market/api/v1/glowhalo/open-graph-validator-api/v1/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<html><head><title>API Market</title><meta property=\"og:title\" content=\"API Market\"><meta property=\"og:image\" content=\"https://api.market/img/brand/logo.png\"><meta name=\"twitter:card\" content=\"summary\"></head></html>", "url": "https://api.market/"}'
```

**Example Response (200 OK):**

```json
{
  "found": true,
  "grade": "D",
  "score": 65,
  "summary": {
    "errors": 0,
    "warnings": 3,
    "infos": 5
  },
  "preview": {
    "title": "API Market",
    "description": null,
    "image": "https://api.market/img/brand/logo.png",
    "url": "https://api.market/",
    "siteName": null,
    "type": null,
    "twitterCard": "summary",
    "locale": null
  },
  "tags": {
    "openGraph": {
      "og:title": "API Market",
      "og:image": "https://api.market/img/brand/logo.png"
    },
    "twitter": {
      "twitter:card": "summary"
    },
    "article": {},
    "canonical": null,
    "title": "API Market"
  },
  "assumptions": {
    "url": "https://api.market/",
    "note": "Validated offline: the og:image file is not requested."
  },
  "issues": [
    {
      "severity": "warning",
      "code": "og_type_missing",
      "message": "No <meta property=\"og:type\"> (usually \"website\" or \"article\"). The Open Graph protocol lists it as required."
    },
    {
      "severity": "warning",
      "code": "og_url_missing",
      "message": "No <meta property=\"og:url\">. Platforms then guess the canonical address of the page."
    },
    {
      "severity": "warning",
      "code": "og_description_missing",
      "message": "No <meta property=\"og:description\">; link cards show no description text or a random page snippet."
    },
    {
      "severity": "info",
      "code": "og_site_name_missing",
      "message": "No og:site_name; some platforms show it above the title."
    },
    {
      "severity": "info",
      "code": "og_image_size_missing",
      "message": "og:image:width / og:image:height are not set; scrapers must download the image first, so the first share can render without it."
    },
    {
      "severity": "info",
      "code": "image_alt_missing",
      "message": "No og:image:alt or twitter:image:alt text for the preview image."
    },
    {
      "severity": "info",
      "code": "twitter_site_missing",
      "message": "No twitter:site (the @handle of the site); optional but used for attribution."
    },
    {
      "severity": "info",
      "code": "meta_description_missing",
      "message": "No <meta name=\"description\">; used by search engines and as a fallback on some platforms."
    }
  ],
  "checkedAt": "2026-10-17T16:01:27.863Z"
}
```

### Issue codes

**Errors:** `og_title_missing`, `og_image_missing`, `og_image_relative`, `og_image_invalid`, `og_url_invalid`, `twitter_card_invalid`, `twitter_image_missing`, `twitter_image_relative`, `og_image_unreachable`, `og_image_not_image`, `og_image_too_large`, `no_social_tags`.

**Warnings:** `og_type_missing`, `og_url_missing`, `og_description_missing`, `twitter_card_missing`, `og_url_canonical_mismatch`, `duplicate_og_tags`, `og_image_too_small`, `og_image_not_https`, `og_image_format_unsupported` (SVG), `og_image_too_large_for_x`, `title_tag_missing`, `meta_description_missing`.

**Infos:** `og_image_size_missing`, `og_title_long`, `og_description_long`, `image_alt_missing`, `twitter_site_missing`, `og_site_name_missing`, `og_image_small`, `og_image_ratio`, `og_image_webp`, `og_image_not_checked`, `html_truncated`.

## Status Codes

| Code | Meaning |
|---|---|
| 200 | The report was produced. |
| 401 | The `x-api-market-key` header is missing or the key is invalid. |
| 403 | Your subscription does not include this endpoint, or the trial has ended. |
| 400 | Bad input (for example `missing_url`, `invalid_url`, `forbidden_host` for private-network targets). The body has `error`, `message` and a usage hint. |
| 413 | `payload_too_large` on `/v1/validate` (body over 512 KB). |
| 502 / 504 | The page could not be fetched or did not answer within 10 seconds. |
| 429 | The trial or monthly quota is used up (hard limit). Back off before retrying and honour any `Retry-After` header. |

## Rate Limits

The Free trial includes 500 requests. The Basic plan includes 25,000 requests per month as a hard limit: when the quota is used up the API returns `429 Too Many Requests` instead of billing overage. Both plans allow up to 10 requests per second; going faster also returns `429`.

## FAQ

**Is this a link-preview scraper?**

No. It is a validator: it tells you what is wrong with a page's social tags and returns a graded report. It does not aim to extract metadata for display. The `preview` object is a best guess (Open Graph first, then Twitter, then the page's own tags); each platform picks its own fields, and this API does not reproduce what a platform crawler sees.

**Does it refresh the preview cache of Facebook, X or LinkedIn?**

No. Platforms cache previews on their side and this report does not refresh them.

**How is the image checked?**

By default with a single 1-byte ranged GET (up to 3 redirects). Type and size come from response headers, and the size check is skipped if the host does not report a size. Image dimensions come from the `og:image:width` and `og:image:height` tags, not from the file. Image hosts that block automated or datacenter requests can produce `og_image_unreachable`. Use `probe=0` to skip the image request.

**Are JavaScript-injected tags detected?**

No. Only tags present in the HTML the server returns are read; there is no JavaScript rendering.

**How are the grade and score calculated?**

The score is 100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total, with a minimum of 0. One error scores 75 (grade C), so gate on `summary.errors`. `unchecked` (the page answered HTTP 4xx/5xx) and `no_social_tags` are not passes.

**Can I check internal or staging pages?**

Only if they are reachable from the public internet. Private-network page URLs are rejected, and a private-network image URL is not requested (flagged as `og_image_not_checked`). Use the validate endpoint with the HTML instead.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Open Graph and Twitter Card validator API (not a scraper) that checks a URL or HTML and returns coded issues, an image check, a grade and a score.

Open Graph & Twitter Card Validator API