Why public-data Skills need a unified response envelope

In short: This is the response-contract article: public platforms differ, but agents need one envelope for pagination, billing, errors, and records.

Every public-data source returns a different response shape. TikTok wraps results one way, Reddit another, YouTube another, LinkedIn another. If your agent talks to all of them directly, it inherits all of that variation — pagination logic forks, retry policies fork, error parsing forks. We solve this by pushing every operation through one envelope. This is the schema and why it matters.

The problem

Source variation is the silent tax on multi-platform agents. The agent's tool-use loop has to handle many shapes, and that complexity shows up in three places that are expensive to maintain: the prompt (the model has to be taught each shape), the retry policy (different sources page differently after failure), and the error envelope (one platform's unauthorized response looks nothing like another's).

We watched our own demo agents spend most of their tokens on shape-juggling instead of reasoning, and decided the right fix was at the gateway, not the agent.

The UnifAPI envelope

Every HTTP endpoint we expose, across every platform, returns the same outer shape: { request_id, data, pagination?, billing }. The fields inside data are platform-specific — a TikTok video has hashtags, a Reddit post has subreddit — but everything around it is consistent.

Errors collapse into a closed vocabulary. Each carries a human-readable message and a machine-readable type. The model can branch on the type without having to recognize platform-specific text.

Reshape patterns we use

Standardizing public platforms behind one envelope means our reshape layer is a few hundred lines per platform. Three patterns dominate.

Cursor unification — every platform's pagination token (max_cursor, after, nextPageToken, end_cursor, page) becomes pagination.cursor. We compute has_more from whatever signal the source provides (length === limit, an explicit has_more flag, a null next-cursor).

Field flattening — when a source nests data three levels deep (data.data.children.data, looking at you Reddit), we lift it to top-level data[]. The model never sees the intermediate envelopes; it sees the records.

Defensive parsing — public platforms change field types without notice (a count becomes a string, an array becomes a single item, a timestamp becomes null). The reshape layer coerces each field to its declared type and drops the record only if the required fields are missing. That discipline catches most silent failures we saw in raw passthrough.

What breaks if you skip this

Without an envelope, two things go wrong at scale. First, your agent prompt grows linearly with platform count — every new platform adds a paragraph explaining its response shape. By platform 10, the prompt is the slowest part of the call.

Second, your retry and pagination code grows multiplicatively. Each source-specific quirk interacts with each other quirk, and the matrix of "does retry-after-cursor work on platform X under condition Y" blows up. Teams that don't normalize early end up writing a normalization layer late, after the bugs.

What's next

The current envelope covers list-style endpoints cleanly. The next iteration we're working on covers streaming and webhook-shaped sources — places where the response isn't a one-shot { data: [...] } but a series of events over time. We're shaping it to feel like an async iterator from the agent's side so the prompt change is minimal.

If you're building a multi-platform agent today and want to see how the envelope plays out in practice, start with a Skill at unifapi.com/skills or inspect the OpenAPI spec at unifapi.com/openapi.json — every endpoint, every field, one shape.

What to read next

MCP catalog tool design - shows how agents discover the operations returning this envelope.

UnifAPI vs RapidAPI - uses normalization as a comparison point.

OpenAPI spec - exposes the live schema behind the prose.