Inspect Endpoint

The primary endpoint for media URL inspection. Supports profile-based projection, field selection, and expansion controls.

POST/api/v1/inspect

Analyzes a public URL to detect its MIME type, category, metadata, and streamability without fully downloading it.

Request

Body Parameters

Field	Type	Required	Description
url	string	Yes
webhookUrl	string	No	Optional webhook URL to receive asynchronous completion events.

Query Parameters

Parameter	Values	Default	Description
profile	fast, standard, full	standard	Projection profile controlling payload visibility
fields	Comma-separated namespace names	All	GraphQL-style field projection
expand	embedHtml, rawHeaders	None	Include normally-hidden fields
debug	true, false	false	Enable debug mode (required for some expansions)

Example Request

curl -X POST "https://api.urlmediainspector.dev/api/v1/inspect?profile=full" \\
  -H "Content-Type: application/json" \\
  -d '{"url": "https://youtu.be/GLTTI1NFHus?si=okdNMy6_p0VSqZJG"}'

Response Envelope

Every response follows a consistent envelope structure. The envelope separates lifecycle truth, processing state, data payload, enrichment provenance, and projection metadata into distinct semantic layers.

{
  "success": true,
  "responseSource": "fresh",       // "fresh" | "cache" | "inflight"
  "cached": false,
  "processing": {
    "status": "complete",           // "partial" | "complete"
    "completion": 1,                // 0.0 → 1.0
    "enrichmentsPending": false,
    "completedStages": ["semantic", "mediaFormat", "oembed"],
    "pendingStages": []
  },
  "data": { /* profile-projected payload */ },
  "enrichmentSources": { /* immutable provenance */ },
  "projection": { "profile": "full", "hiddenFields": [] }
}

HTTP Status Codes

Status	Description	When
200	Inspection complete	FAST, FULL, or cached STANDARD
202	Enrichments processing	STANDARD on heavy media
400	Invalid URL or bad request	Error condition
403	SSRF protection blocked the request	Error condition
500	Internal server error	Error condition

Data Namespaces

The data block contains profile-projected namespaces. See Response Envelope for full namespace documentation.

Namespace	Presence	Description
identity	Always	URL, final URL, canonical URL, MIME
semantic	Always	Kind, semantic type, title
playback	Always	Strategy, component, stream/download
metadata	Always	File info + category sub-object
provider	Provider only	Name, confidence, detection method
preview	Profile-dependent	Thumbnails, placeholders, palette
diagnostics	FULL only	Performance timings

Related

• Projection Profiles — FAST, STANDARD, FULL behavior
• Response Envelope — envelope structure details
• Progressive Enrichment — lifecycle semantics
• Response Examples — curated real responses

---

Job Status

GET/api/v1/job/{id}

Retrieve the status of an asynchronous enrichment job. Job IDs are returned in 202 Accepted responses when STANDARD profile encounters heavy media.

Path Parameters

Parameter	Type	Description
id	string	Job ID from the inspect response

Response

{
  "job": {
    "id": "job_abc123",
    "status": "processing"   // "processing" | "complete"
  }
}