Projection & Fields

The platform supports GraphQL-style field projection via query parameters. Projection controls which data namespaces appear in the response without affecting orchestration or processing state.

Field Projection

Use ?fields= to request specific data namespaces:

# Only semantic block
curl -X POST "https://api.urlmediainspector.dev/api/v1/inspect?fields=semantic" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video.mp4"}'

# Multiple namespaces
curl -X POST "https://api.urlmediainspector.dev/api/v1/inspect?fields=semantic,playback" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/GLTTI1NFHus"}'

Projection Response

// ?fields=semantic — only semantic block returned
{
  "success": true,
  "processing": { /* still valid — projection doesn't affect this */ },
  "data": {
    "semantic": {
      "kind": "direct-media",
      "semanticType": "video"
    }
    // identity: projected out
    // playback: projected out
    // preview: projected out
    // metadata: projected out
  }
}

Projection Rules

Rule	Behavior
Processing state	Always valid — projection never affects processing
Empty objects	Never present — projected data is sanitized
Orchestration	Unaffected — projection is a pure view operation
Profile compatibility	Works with any profile (?fields=semantic&profile=full)

Expansion Controls

Use ?expand= to include normally-hidden fields:

# Include embed HTML in FAST profile
curl -X POST "https://api.urlmediainspector.dev/api/v1/inspect?profile=fast&expand=embedHtml" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/GLTTI1NFHus"}'

# Include raw headers (requires debug mode)
curl -X POST "https://api.urlmediainspector.dev/api/v1/inspect?expand=rawHeaders&debug=true" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

Available Expansions

Expansion	Effect	Requirements
embedHtml	Includes playback.html in FAST profile	None
rawHeaders	Includes network.headers block	?debug=true

Profile-Based Projection

Profiles apply automatic field projection. See Projection Profiles for the full projection matrix.

Hidden Fields Declaration

When a profile hides fields, the projection.hiddenFields array declares what was intentionally omitted:

// FAST direct media — preview is projection-hidden
{ "projection": { "profile": "fast", "hiddenFields": ["preview"] } }

// FAST provider media — provider-native preview is visible
{ "projection": { "profile": "fast", "hiddenFields": [] } }

// FULL — nothing hidden
{ "projection": { "profile": "full", "hiddenFields": [] } }