# FetchPI Agent Skill

Sketch: FetchPI is a data API platform. It serves structured public internet
data (social, video, e-commerce, trends, news platforms) through stable,
normalized JSON endpoints. One API key, pay-per-call Credits, five interface
languages. This file teaches an agent how to discover, price and call the
APIs correctly.

## When to use FetchPI

Use it when a task needs public platform data: a user profile, a post or
video, comments, follower lists, search results, product or trend data.
Do NOT guess whether a platform is supported — check the catalog first
(every platform has an explicit availability status).

## Authentication

Every data call needs one API Key. The user creates keys in the console
(sign up at https://fetchpi.com — new accounts include free trial Credits):

```
Authorization: Bearer <api_key>
```

Keys are shown once at creation. If a call answers 401, the key is missing,
revoked, or mistyped — ask the user, never retry blindly.

## Workflow: discover → inspect → call → read usage

1. **Discover.** The catalog lists every platform, its availability status
   and its cheapest per-call price:

   ```
   curl -s https://fetchpi.com/api/v1/catalog/products
   curl -s https://fetchpi.com/api/v1/catalog/products/tiktok
   ```

   `status: "active"` means callable. `coming_soon` / `disabled` platforms
   are NOT callable — do not try them.

2. **Inspect.** Every endpoint's path, parameters and response schema are in
   the public contract (data + catalog paths only):

   https://fetchpi.com/openapi.yaml

   Per-platform docs with examples: https://fetchpi.com/en/docs
   Read the schema before calling — never guess parameter names.

3. **Call.** Data endpoints live under `/v1/{platform}/...`, e.g.:

   ```
   curl -s -H "Authorization: Bearer $FETCHPI_KEY" \
     "https://fetchpi.com/v1/x/users/{username}"
   ```

   Freshness control (optional, every endpoint):
   `?freshness=cache|default|live` or `?max_age=<seconds>`.
   `live` may cost extra Credits; cached data is the cheapest path.

4. **Read usage.** The response envelope carries request cost metadata; the
   console (https://fetchpi.com/en/console) shows per-key usage and balance.

## Billing rules (predict cost before calling)

- Billing is per successful call, priced per endpoint in Credits
  (`from_price_credits` in the catalog; the pricing page lists every price).
- List endpoints may bill by the items requested — keep `limit`/`max_items`
  small on the first call and paginate only as far as the task needs.
- Upstream failures are not billed; a cached answer bills the (lower) cache
  price where marked.
- The user's balance is shared across all their keys. Spend responsibly:
  prefer `freshness=cache` for repeated lookups, and stop paginating once
  the task's question is answered.

## Hard rules

- Never invent endpoint paths — only call paths documented in the catalog
  or the OpenAPI subset.
- Never present a `coming_soon` platform as available.
- Respect the platform's legal/ToS constraints; FetchPI serves public data
  only.
- If a call answers `402 INSUFFICIENT_CREDITS` or `429 RATE_LIMITED`, report
  the balance/rate state to the user instead of retrying.