Skip to main content
Scenario Methods are the way to call AgentKey from code — built for developers and enterprise integrations, while agents on the MCP server use the tool catalog. Each method has a fixed name, a fixed input schema, a fixed output schema and a fixed price. AgentKey picks the upstream provider, normalizes the response, fails over when a provider breaks, and tells you exactly what it did.
If you are wiring an agent to the MCP server instead, the catalog’s find_tools → describe_tool → execute_tool flow is documented under Tool Catalog; Two Ways to Call explains when to use which.
Scenario Methods are in beta. Schemas may still gain fields; we avoid breaking changes and version them when unavoidable (see Stability and versions).

​
Method names

A method is named domain.platform.action, or domain.action where there is no platform: The name is the same identifier everywhere: in the REST path, in the catalog, in the OpenAPI operationId (dots become underscores) and in future SDKs. Within a domain the same action means the same thing on every platform — post.search on X and on Xiaohongshu take the same core parameters and return the same Post object.

​
What is covered

Public methods span ten domains. Social and e-commerce methods come in platform × action combinations; the other domains are provider-independent lookups. Browse them in the sidebar, or fetch the live catalog:

​
Why fewer methods than catalog tools

The catalog lists every upstream endpoint; Scenario Methods are a curated layer on top of it, so there are far fewer of them. That is by design:
  • One method per capability. A method such as social.x.post.search stands in for every endpoint that does that job — several providers, their app and web variants, their v1 / v2 / v3 generations. Where the catalog shows many tools, the method shows one, and the server chooses among them.
  • Stability over coverage. A method is a contract: fixed schema, integer versions, additive changes only. Catalog tools follow their provider and can be renamed or dropped whenever the provider changes. An operation becomes a method only when its contract can be kept for years.
  • Normalized output. Methods return shared objects — Post, Product, Quote, … Endpoints whose data does not map onto one of those objects — platform-specific analytics, raw feeds, login-state or ad-ops operations — stay in the catalog.
  • Validated against real responses. A method ships only after every provider behind it has been sampled with real calls and its field mapping checked against recorded responses. New providers therefore appear in the catalog first; the method list lags it on purpose.
  • The common tasks first. Methods cover what agents ask for most — search posts, fetch a product, quote a symbol, scrape a page. The long tail is a find_tools call away.
If a capability you need is in the catalog but not yet a method, call it through the catalog today and tell us: methods are added where usage shows demand.

​
The contract

Every method gives you the same guarantees:
  • Strict input. The input schema is exact; an unknown field is a 400, not a silent no-op. See Requests.
  • Normalized output. Results are mapped to shared objects — Post, User, Product, Quote, … — whatever provider served the call. Fields a provider structurally lacks are declared in unsupported_fields, so null always means “this record has none”. See Responses.
  • One price. Charged once per successful call, the same whichever provider answered. Failed attempts are refunded. See Routing & Pricing.
  • Nothing hidden. The envelope names the provider, lists every attempt, reports credits_charged and carries a request_id.
  • Readable without a key. The catalog, every method’s describe and the OpenAPI document are public, so you can evaluate the contract before you sign up.

​
Stability and versions

Each method carries a tier in the catalog and in x-stability in the OpenAPI document: Versions are integers at two levels:
  • The surface version is in the path: /v2. It changes only when the envelope, the reserved parameters or the shared objects change incompatibly.
  • The method version is a suffix on the name: social.x.post.search is version 1; a breaking change ships as social.x.post.search.v2 while the old name stays available through its sunset. The envelope reports the version that served you as op_version.
What counts as breaking: removing a field, changing its type or meaning, making an optional input required, changing what an enum value means. What does not: adding an optional input, an output field, an enum value, a platform or a method. Write clients to ignore output fields they don’t know.

​
Reading a method page

Each method page in the sidebar is generated from the same OpenAPI document the server serves at /v2/openapi.yaml. It shows the request body with every parameter, the success envelope for that method’s output type, the error responses, and the providers behind it (x-providers). For live information — provider health right now, which fields each provider cannot supply, and a recorded example response per provider — call GET /v2/ops/{method}.

Quickstart

Catalog, describe and your first call in three curl commands.

Requests

Authentication, shared parameters, reserved fields, pagination.

Responses

The envelope and the shared objects.

Routing & Pricing

Provider selection, failover rules, fixed prices, overrides.