URL To Metadata

POST https://api.echovalue.dev/url-to-metadata

Fetches metadata for a public URL through the echoValue URL To Metadata service.

The request is authenticated with x-token, charged by echoValue, and logged.

Request

Headers:

Header	Description
`x-token`	Your API token
`content-type`	Must be `application/json`

Body:

Field	Type	Required	Description
`url`	string	Yes	Public URL to analyze
`aiSummary`	string	No	AI enrichment level: `none`, `short`, `medium`, or `long`. `none` is the default

Examples:

curl 'https://api.echovalue.dev/url-to-metadata' \
  -H 'x-token: mytoken' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/article",
    "aiSummary": "short"
  }'

Response

200 OK returns the JSON payload produced by the URL To Metadata service.

{
  "success": true,
  "data": {
    "seo": {
      "title": "Example Company - Leading SaaS Platform",
      "description": "Enterprise software for team collaboration",
      "keywords": ["saas", "collaboration", "enterprise"],
      "canonical": "https://example.com"
    },
    "technical": {
      "statusCode": 200,
      "finalUrl": "https://example.com",
      "originalUrl": "https://example.com/article",
      "robotsAllowed": true,
      "isSecure": true,
      "contentType": "text/html; charset=utf-8"
    },
    "links": {
      "internal": {
        "total": 12,
        "urls": ["/about", "/pricing", "/contact"]
      },
      "external": {
        "total": 2,
        "urls": ["https://github.com/example"],
        "domains": ["github.com"]
      }
    },
    "ai": {
      "summary": {
        "short": "Example Company provides cloud-based collaboration software for enterprises.",
        "contentLength": 5240,
        "truncated": false
      },
      "keyFacts": {
        "companyName": "Example Company Inc.",
        "industry": "Enterprise Software",
        "businessModel": "Subscription"
      },
      "processingTime": 2340
    }
  },
  "timestamp": "2025-06-19T15:54:01.821Z"
}

The response shape is partially flexible. Top-level fields such as success, data, and timestamp are stable, while nested keys inside data can vary depending on the target page and whether AI enrichment is enabled.

Response Shape

Field	Type	Description
`success`	boolean	Indicates whether the scrape completed successfully
`data`	object	Extracted metadata grouped by area such as `seo`, `technical`, `links`, `social`, `contact`, and `ai`
`timestamp`	string (ISO 8601)	When the response was produced

When aiSummary is none, the ai block may be omitted. When AI enrichment is enabled, data.ai.summary, data.ai.keyFacts, and data.ai.processingTime may be returned.

Response headers:

Header	Description
`x-balance`	Wallet balance after this call
`x-cost`	Credits consumed for this request

See Response Headers for details.

Status Codes

Status	Meaning
`200`	Metadata returned successfully
`400`	Invalid request body or validation error
`401`	Invalid token
`402`	Wallet has insufficient credits
`405`	Method not allowed
`500`	Internal service error
`502`	Metadata service unavailable
`503`	Metadata service unavailable

Notes

The target URL must be publicly reachable by the metadata service.
Treat nested fields inside data as optional and schema-light. Parse defensively.
This endpoint is best suited for metadata extraction, link analysis, and optional summary generation over public pages.