Caching with max_age

Agents often ask the same question twice in one session. max_age lets a call reuse a recent response instead of calling the provider again, which is faster and, for paid providers, cheaper.

How it works

Add max_age in seconds to any call:

curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gsc","tool":"gsc_top_queries","input":{"siteUrl":"sc-domain:example.com"},"max_age":3600}'

• If a successful response for the same connection, endpoint or tool, and input is at most max_age seconds old, it is returned with "cached": true. The provider is not called and the call costs nothing.
• Otherwise the provider is called as usual, and the fresh response is stored for later calls that pass max_age.
• Without max_age, the call always goes to the provider and nothing is stored.

max_age accepts 0 to 604800 (7 days). "max_age": 0 always fetches fresh data and stores it, which is useful to warm the cache before a batch of calls. Only successful responses are cached, and cached responses are kept for at most 7 days.

Choosing a value

Matching uses the validated input, with defaults filled in: {"days": 28} and {"days": 30} are different entries, while leaving days out matches {"days": 28} because 28 is the default. Key order doesn't matter.

In the logs

Cached calls are logged like any other, with cached: true, so you can see how often your agents reuse data.