Unified Data API Getting Started: From Capability Catalog to First Available Result

Writing request code for a single platform is usually straightforward. The real friction starts when the second platform comes in: parameter names change, user and content identifiers differ, some endpoints return data immediately while others create tasks first. Once cron jobs begin running, retry logic, deduplication, and billing reconciliation each grow their own separate code paths.

The unified data API addresses this redundant integration overhead. In the EveryInfra of EveryData, you use the same Bearer authentication, selecting the platform via platform, the capability via action, and passing capability-specific parameters via params. What is unified is the call entry point and general handling flow, not a forced homogenization of all platform data into a single business object.

This tutorial demonstrates a minimal request using Xiaohongshu note search, then explains how to scale to other capabilities. The goal is not just executing a single HTTP request, but ensuring your program knows what data it retrieved, which results remain pending, and how the next run should bridge the gap. Examples are based on public catalogs and implementations verified against 2026-09-04; production POST snippets serve as call templates for permitted scenarios rather than newly measured live successes.

Determine First: Do You Need Data Retrieval, or Search and Generation

If you already know the platform a target belongs to—such as a specific note, product, or location—and want to read its structured fields, the data API is the right starting point. If you are still asking where materials exist online, run web search first; if you already possess the materials and need summarization, classification, or report writing, use model processing.

Taking comment analysis as an example, collection answers what these comments are and where they originate, while models answer what issues appear in these texts. The latter cannot invent missing records caused by collection failures, nor interpret unreturned comment counts as zero. Separating these two phases allows you to return to original evidence when conclusions are contested, rather than reguessing the entire call chain.

Step 1: Confirm Capabilities via the Catalog, Don't Guess Endpoints from Platform Names

The capability catalog can be read without an API Key. Use the compact version first to understand available platforms and actions, then fetch the full contract for your selected platform. The compact view is for discovery and omits parameter and field descriptions; do not treat the concise catalog as a full request validator.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?compact=1' \
  | jq '.capabilities[] | {platform, action, required_params, mode, available}'

For example, to find Xiaohongshu notes related to a research keyword, check search first; if you already hold a note link and want details or comments, select note or comments accordingly. Similar names do not imply interchangeability: search keywords cannot be passed directly as detail request URLs.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=xiaohongshu' \
  | jq -e '.capabilities[] | select(.action == "search") | {
      platform, action, required_params, optional_params,
      param_meanings, mode, returns_list,
      default_limit, max_limit, response_fields, available
    }'

In this catalog verification, required parameters for xiaohongshu.search are keyword, with mode set to sync and returns_list set to true; default count is 20, with an upper limit of 50. The latter two describe quantity settings for this capability, not a delivery guarantee per request or a cross-platform universal limit. The catalog also lists sort and content_type; when filtering, use allowed values from param_meanings and do not copy enumerations from another platform.

• required_params: Mandatory inputs required. Satisfy these first before adding filters incrementally.
• param_meanings: Parameter definitions and declared allowed values. Do not invent custom enumerations for unlisted fields.
• mode and returns_list: Determine whether task polling is required and whether the final business data is a list or single object.
• response_fields: Used to plan field mappings; not a live response nor a guarantee that every field has a non-empty value.
• available: Catalog-level availability flag; it does not pre-prove that a target URL will return data right now.

List capabilities also support general limits, which may not repeat inside optional_params. This distinction is verified by request validation code. When integrating, review list declarations, defaults/limits, and full descriptions together; do not strip valid limit parameters simply by doing string matching against optional_params.

Step 2: Send a Request Small Enough to Inspect Easily

Prepare an API Key with appropriate capability permissions and supply it via server environment variables. Avoid placing it in browser frontend code, screenshots, or publicly downloadable example files. The examples below assume EVERYINFRA_API_KEY is configured via your own secret management; commands submit a single request with no automatic retries.

: "${EVERYINFRA_API_KEY:?set the server-side API Key first}"
curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "platform": "xiaohongshu",
    "action": "search",
    "params": {
      "keyword": "AI tools",
      "limit": 5
    }
  }'

The 5 here represents your target small sample size rather than a delivery guarantee; 180 seconds is the client wait timeout for this example, not a service SLA. Confirm fields, timestamp formats, and source links with a small result set before scaling up volume. Retain HTTP status lines and response bodies during initial debugging so specific errors can be read upon encountering 4xx or 5xx codes instead of a generic curl failure notice.

Three top-level fields must remain distinct: platform and action select the capability, while all business conditions go into params. Do not elevate keyword to the top level, nor attach page, cursor, or sort to actions that do not support them. Parameters absent from the catalog cannot be assumed supported simply because most APIs are designed that way.

OpenAPI helps humans and programs describe request bodies, parameters, and responses, but it does not mandate identical business models across platforms. When generating types or building callers, use specifications to understand interface description formats, then rely on the service's own catalog and response contracts to determine exact fields.

Step 3: Understand the Outer and Inner Structure of Synchronous Results

For the selected xiaohongshu.search, the implementation places lists inside results alongside outer metadata including id, platform, action, count, billing, and quota. The id is the request tracking identifier, while the id of each record inside results is the content identifier. Do not conflate the two: use the former for debugging and reconciliation, and the latter for record deduplication.

Do not treat results as the sole retrieval path for every client. Other actions may return business objects with different names; returns_list indicates object shape, and field dictionaries explain internal fields, but neither replaces verifying the outer structure of the chosen capability. Adding a new capability requires a clear result adaptation config rather than recursively searching every response for the first array.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=xiaohongshu&action=search' \
  | jq '{fields, undocumented}'

Two field-handling details frequently affect conclusions. First, null engagement metrics indicate unpublicized or unavailable data and should not be automatically backfilled with 0 before computing averages. Second, public documentation for posted_at permits raw platform timestamp strings to be preserved; do not assume all values parse directly into a single ISO format. Store parsed timestamps separately and retain a status flag for parsing failures rather than populating failed dates with today.

If responses include partial or missed flags, un-delivered targets must be tracked separately; HTTP 200 does not guarantee every target in a batch yields data. For empty arrays, the only valid conclusion is that no records were returned this time, not that data is absent from the original platform. Whether requests covered the correct objects and adhered to scope limits is a separate question.

Step 4: Await Terminal States for Asynchronous Capabilities, Don't Stop at job_id

When switching to capabilities with mode set to async, submission responses may return HTTP 202 along with status, job_id, and poll_url. Persist these fields before initiating task queries. HTTP specification 202 indicates a request has been accepted but processing is incomplete; do not use it to trigger business notifications like report generated.

: "${EVERYINFRA_API_KEY:?set the API Key used for this task first: API Key}"
: "${EVERYINFRA_JOB_ID:?paste the job_id from the actual submit response}"
curl --silent --show-error --include --max-time 30 \
  "https://api.everyinfra.com/api/v1/jobs/${EVERYINFRA_JOB_ID}" \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}"

Current query implementations look up jobs based on the Key used at submission time. Query using the same Key, and do not assume switching Keys under the same account will retrieve the task; if unfound, do not immediately recreate an identical task. Verify API domains, job_ids, and keys used, falling back to saved request info when necessary.

• running or finalizing: Processing states. Retain the task and continue polling at bounded intervals.
• succeeded: Task reaches a successful terminal state; parse the capability data object and verify business requirements.
• failed: Reaches failure terminal state; read error and retain task records without treating it as empty-data success.
• Query timeout or unknown status: Mark as unconfirmed only. Set total wait budgets for subsequent recovery workflows without altering to success or failure.

Pollers should enforce maximum wait times with gradually backing-off intervals to prevent tight loops. Upon program restart, resume polling from saved job_ids rather than resubmitting tasks. Save submission billing separately: current result query responses do not repeat complete billing blocks, so absence of billing in query results does not imply zero charges.

Microsoft's Asynchronous Request-Reply pattern also separates acceptance, status checking, and final results while discussing polling hints. It serves as a useful design reference for client workflows; headers like Location and Retry-After are not return guarantees for EveryInfra here, and actual queries continue using the entry point provided in the current response.

Step 5: Handle Errors by Root Cause, Especially Without Blind POST Retries

Business errors require checking HTTP status and error.code simultaneously. Current data entry points check authentication first, then capabilities, permissions, and parameters, before entering quota and execution flows. Seeing 401 when lacking a valid Key does not confirm that your business parameters passed validation.

• 401: Verify Key existence, validity, and correct Bearer headers. Do not attempt to fix auth failures by modifying keywords.
• 403: Verify Key authorization for target products and capabilities. Permission issues should be handled by authorized personnel without auto-switching accounts.
• 400 unknown_capability: Check platform and action matching; re-read catalogs and review service-provided candidate names.
• 422: Check required items, unknown parameters, and illegal enums. Address one error per prompt before issuing new requests.
• 402: Insufficient quota; account credit issues must be resolved; repeating identical requests will not change this.
• 429, temporary service errors, or network drops: Back off and determine original request states. Retry with bounded limits only when verified safe.

The easiest detail to overlook is client timeouts where servers may have already accepted requests. Data fetching appears read-only from a business perspective, but executes via POST, potentially creating tasks and incurring charges. Correlation IDs help associate multiple attempts but do not automatically provide server-side idempotency guarantees. Do not inject Idempotency-Key headers without explicit API support and assume duplicate requests execute only once.

RFC 9110 places strict limits on automatic retries for non-idempotent requests. For such unknown outcomes, query existing tasks or check request records first; retaining unknown status when data is insufficient is safer than auto-replaying entire batches.

Step 6: Store Data, Collection Status, and Billing Separately

The most valuable aspect of unified entry points is clarifying division of labor between general records and platform field mappings. Maintain at least three types of records: a business task, an API attempt, and a platform object. This tracks how many attempts a task underwent while allowing identical content updates across multiple collections without creating duplicate new objects.

• Task records: Your task_id, target scope, expected fields, and completion criteria. Completion here is business-defined, not just HTTP success.
• Request records: platform, action, non-sensitive parameter summaries, start/end times, API request IDs, job_ids, status, and billing. Retain failed attempts.
• Object records: platform, object type, object id, source links, actually acquired fields, and observed_at; do not merge coincidental cross-platform ID collisions.

These are application data model recommendations, not extra fields returned by EveryInfra. observed_at should be logged by collectors to denote observation time, while posted_at indicates original content publication time. Using both answers when content was published versus when we knew about it, enabling analysis of delayed data and repeated observations.

When performing cross-platform comparisons, map only business-required fields with comparable semantics. Likes, bookmarks, product ratings, and comment counts are distinct metrics; uniformly renaming them to score does not grant them a unified scale. For uninterpreted fields, preserve missing states or check dictionaries rather than guessing units and meanings.

Billing cannot be reverse-engineered from result item counts. Multi-target capabilities bill per target, meaning HTTP requests are not billing units; small sample limits do not imply proportional discounts on returned counts. Current sync implementations handle empty results and partial delivery billing refund branches, but your client must persist actual billing and ledger records for auditing; do not declare accounts settled solely based on 200 or empty arrays.

Refer to OWASP interaction ID designs when logging requests: correlate events under single business intents while excluding sensitive items like access tokens. Retaining debuggable info is not equivalent to dumping request headers and raw text into logs.

Which Code is Worth Reusing When Scaling to a Second Platform

Auth injection, timeout settings, error logging, task query schedulers, and security logging are reusable. Code that must remain capability-specific includes parameter names and semantics, result object paths, field mappings, pagination rules, and completion criteria. Separating both halves prevents adding future capabilities from turning into copy-pasting entire client suites.

Catalogs benefit from observation-time caching, re-verified before integrating new capabilities or releasing updates. Avoid infinite cache lifespans, but don't download full catalogs per record either; set refresh intervals according to business change tolerance, triggering targeted re-checks only upon unknown_capability or contract conflicts.

Pagination and increments require exceptional caution. Proceed only when specific actions explicitly provide pagination parameters and termination signals; never synthesize client-side cursors without them. Cron queries yield multiple observations and do not automatically equal complete histories or all new content. Version one reports should explicitly state checked targets and time windows rather than claiming unprovable full coverage.

Which Tasks Are Unsuited for Direct Application of This Approach

If you need to post on behalf of users, manage merchant profiles, handle account authorizations, or modify platform data, check official platform APIs and authorization workflows instead of treating public data endpoints as account management interfaces. For private content, restricted data, or unpermitted use cases, unified endpoints do not expand your access privileges.

Even when data is publicly visible, storage, analysis, and re-display must be evaluated against specific platform rules and business purposes. Restrict research scopes to necessary targets and fields, control retention periods, and avoid outputting author profiles, access-parameterized links, or raw text directly into public logs. Technical request capability and business usage permission are two distinct checks.

Start From One Explainable Result

Upon completing initial integration, ask yourself four questions: Can I clearly articulate the specific capability called? Can I trace every data item to its source? Can I distinguish success, processing, partial delivery, and unknown outcomes? If requests fail or duplicate, can I explain the resulting records and billing?

Once all four questions have answers, expand platforms, increase concurrency, and integrate model analysis. The value of unified data APIs is not making all differences vanish, but ensuring you write custom logic only where platform differences genuinely exist. Choose a capability from the docs below, check small samples, save results correctly, and begin your next step.