# OpenGraph Analyzer: API and integration guide

OpenGraph Analyzer extracts metadata from the public, server-rendered HTML of a URL.
It does not execute JavaScript or render a browser.

## Discover this service

- `https://opengraph.wayl.one/llms.txt`: concise service and API summary
- `https://opengraph.wayl.one/llms-full.txt`: this complete guide
- `https://opengraph.wayl.one/agents.md` and `/AGENTS.md`: agent instructions
- `https://opengraph.wayl.one/index.md`: Markdown overview of the service
- `https://opengraph.wayl.one/skill.md`: detailed integration workflow
- `https://opengraph.wayl.one/openapi.json`: machine-readable OpenAPI schema
- `https://opengraph.wayl.one/docs`: interactive API documentation
- `https://opengraph.wayl.one/health` and `/ready`: service health

## Analyze a URL

Send a JSON request:

```http
POST /api/v1/analyze HTTP/1.1
Host: opengraph.wayl.one
Content-Type: application/json

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

Equivalent curl:

```bash
curl -fsS https://opengraph.wayl.one/api/v1/analyze \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/"}'
```

The response uses `schema_version: "v1"` and has top-level `page` and `issues`
fields. Metadata values are arrays so repeated tags are preserved. Read Open Graph
values from `page.open_graph`, Twitter values from `page.twitter`, standard metadata
from `page.standard_meta`, article data from `page.article`, and image/link data from
`page.images` and `page.links`. Each issue includes `field`, `code`, `message`, and
`severity`.

## Errors

- `400`: malformed, unsupported, credential-bearing, private, or otherwise unsafe URL.
- `413`: fetched response exceeds the service body limit.
- `502`: upstream fetch failure, HTTP error, or bot challenge.
- `504`: upstream timeout.

Do not retry unsafe URLs. Treat upstream errors as page-fetch failures and apply a
bounded retry policy only when appropriate. The fetcher follows HTTP(S) redirects and
validates each destination. It rejects private and reserved addresses to prevent
server-side request forgery. Never use this API to access internal services.

## Python and CLI

For a terminal, use `ogcli analyze URL --json`. Inside this repository, use
`opengraph.service.Analyzer` and `AnalysisResult.to_dict()` for the same versioned
result contract.

## Repository validation

Before deploying repository changes, run `just check`. It verifies the lock with
`uv lock --check`, runs the pytest suite with branch coverage and an 80% floor,
checks Ruff lint and formatting, and runs strict `ty check opengraph.py src tests`.