What is a unified schema?
A unified schema means every successful response shares the same top-level shape — one parser instead of one per platform. On Social Fetch that's { data, meta }: logging, billing, and retries don't fork per network. Nested payloads still differ by resource.
The envelope
data holds the platform payload. meta carries requestId, creditsCharged on metered routes, and version — same three keys for TikTok or Spotify.
Errors use a typed code plus meta.requestId. Branch on HTTP status and documented fields, not null vs [] guessing.
A concrete example
Instagram and GitHub profile lookups both return top-level data and meta with the same meta keys. Inside data, shapes diverge — Instagram has follower counts; GitHub has repo counts.
A missing Instagram handle: HTTP 200, data.lookupStatus not_found. A malformed request: typed error envelope, not an empty 200.
Unified does not mean identical fields
A TikTok video and LinkedIn company page don't share every nested key. Unified means stable wrapper and ops metadata; overlapping concepts use consistent names (follower counts, timestamps).
Where documented, read lookupStatus before writing warehouse rows — part of the contract on any route that supports it.
How teams use it in practice
Without a shared envelope, each new platform forks logging, billing, and retry code. With one envelope, adding a platform is mostly a new route under /platforms.
Ask, MCP, and typed REST all parse { data, meta } — prototype code carries to production cron jobs with minimal changes.
How this compares to typical scraper and marketplace APIs
Many marketplaces pass each publisher's raw shape through — new platform, new parser. Unified schema normalizes at the API boundary so requestId and billing live in the same place every time.
Common mistakes and what it is not
Treating HTTP 200 as "found it." 200 with lookupStatus not_found is completed and billed — read lookupStatus first.
Unified doesn't mean identical fields or invented metrics. Not a caching or rate-limit guarantee. Details: /unified-schema, /docs/errors, /openapi.json.
FAQ
What is a unified API schema?
Same top-level shape on every endpoint — Social Fetch uses { data, meta } so requestId and creditsCharged always live in the same place.
Does Social Fetch normalize fields across platforms?
Overlapping concepts yes (followers, timestamps). Platform-specific data stays inside data.
Does Ask use the same schema?
Yes — { data, meta } plus data.routedOperation for the nested lookup.
Where is the OpenAPI spec?
/openapi.json and per-operation pages under /docs/api. @socialfetch/sdk follows the same spec.
Does this cover all 21 platforms?
Yes. Marketplace operations across 21 platforms share the envelope.
Is a 200 response always a successful lookup?
No. Check data.lookupStatus — not_found and private are completed, billed answers.
How is this different from how other scraper APIs structure responses?
Many pass through publisher-specific shapes. Unified schema normalizes wrapper and ops fields at the boundary.