Metadata

Extract structured metadata from a page. URLpipe reads the markup with AI and returns a tidy JSON object — title, description, language, author, publication date, feed URL and main image — normalising the messy variety of meta tags, JSON-LD and microdata found in the wild.

This is an AI operation, metered against your AI allowance.

POST/meta

Extract metadata

Body parameters

Name
url
Type
string
Required
Required
Description
The absolute URL of the page to process. Rendered with headless Chrome, so JavaScript runs and redirects are followed.
Name
report_to
Type
string
Description
Webhook URL — an http or https address URLpipe POSTs the result to when it's ready. Required for async requests (the default); omit it only when you send sync=true. A missing or invalid value returns 422.
Name
sync
Type
boolean
Description
Process the request synchronously, returning the result inline in the response. Defaults to false (async: return a token now, deliver the result to report_to via webhook). See Async & sync modes for the full contract.
Name
max_age
Type
string | integer
Description
How fresh a cached result must be to be accepted. Either an integer number of seconds (3600) or a duration string of the form "<number> <unit>" — units s/min/h/d/w (e.g. "2 hours", "3 days", "30m"). Defaults to 7 days, clamped to a max of 30 days; 0 always bypasses the cache. See Caching for all accepted units.

Response fields

Name
title
Type
string
Description
The page's main title.
Name
description
Type
string
Description
The page description.
Name
language
Type
string
Description
ISO 639-1 language code, e.g. en.
Name
main_image_url
Type
string | null
Description
URL of the main image; null if none or a data URI.
Name
favicon_url
Type
string | null
Description
URL of the favicon; null if none or a data URI.
Name
author_name
Type
string | null
Description
The content author, if any.
Name
feed_url
Type
string | null
Description
RSS or Atom feed URL, if discovered.
Name
publication_date
Type
string | null
Description
Publication date in ISO 8601, if found.
Name
additional_author_information
Type
object | null
Description
Extra author details such as social handles or email, if found.

POST/meta

curl -X POST https://urlpipe.dev/meta \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

const res = await fetch("https://urlpipe.dev/meta", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
})

Response

{
  "title": "Example Domain",
  "description": "Illustrative examples in documents.",
  "language": "en",
  "main_image_url": "https://example.com/cover.jpg",
  "favicon_url": "https://example.com/favicon.ico",
  "author_name": "Jane Doe",
  "feed_url": "https://example.com/feed.xml",
  "publication_date": "2026-01-01T00:00:00Z",
  "additional_author_information": {
    "twitter": "@janedoe",
    "email": "jane@example.com"
  }
}

Any field can be null when the information isn't present on the page. AI endpoints accept up to 1 MB of HTML.

Responses

Status

When

Body

200 OK

The request succeeded.

Sync: the result, in this endpoint's format (see Response above). Async: a job token — { "token": "…", "status": "accepted" }.

422 Unprocessable Entity

The analysis failed, or a parameter was invalid (a bad max_age, or a missing/invalid report_to in async mode).

{ "error": "<message>" }

429 Too Many Requests

You've hit your monthly quota for this operation's category (checked only on a cache miss).

{ "error": "quota_exceeded", "category", "limit", "used", "resets_at" }

504 Gateway Timeout

Sync only: the analysis didn't finish within 60s. It keeps running — fetch it via GET /result/:token.

{ "error": "processing_timeout", "token": "…" }

401 Unauthorized

Missing or invalid API key.

—

Try it live — no API key needed

Run this endpoint against any URL right in your browser.

Open tool

PreviousMarkdown

NextSummarize