# 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.

## Use FetchPI from an MCP client (Claude Desktop, Cursor, …)

FetchPI ships an official MCP server (`fetchpi-mcp`, stdio transport) that
wraps this workflow as five tools: `fetchpi_list_platforms`,
`fetchpi_search_posts`, `fetchpi_get_profile`, `fetchpi_get_user_posts`,
`fetchpi_get_comments`. Build it once from the open-source repository:

```
git clone https://github.com/AI-MeshGate/meshapi
cd meshapi/backend && go build -o fetchpi-mcp ./cmd/fetchpi-mcp
```

Then register it in the MCP client (example: Claude Desktop
`claude_desktop_config.json`; Cursor's `.mcp.json` uses the same shape):

```json
{
  "mcpServers": {
    "fetchpi": {
      "command": "/absolute/path/to/fetchpi-mcp",
      "env": { "FETCHPI_API_KEY": "fp_live_..." }
    }
  }
}
```

The key is read from the environment at startup — never paste it into a
conversation. Tool failures come back as tool results with remediation text
(missing key, insufficient Credits, rate limits), so the agent can report
them instead of retrying.