<!-- Generated by scripts/generate-agent-docs.mjs. Edit the generator or agentConnectionData.ts. -->

# FavStash API

Base URL: **https://mcp.favstash.app**. This documentation page at `https://www.favstash.app/api` is not the API endpoint.

For AI hosts, prefer the [CLI](https://www.favstash.app/cli.md) or [remote MCP](https://www.favstash.app/mcp.md). Custom applications and unattended jobs can call the same owner-scoped backend directly. Create a scoped API key in [AI Connect](https://www.favstash.app/dashboard/connect), store it securely, and send it as a bearer token.

## Read-only smoke test

Set `FAVSTASH_API_KEY` in your private shell environment before running this example; never paste the value into chat.

```sh
curl --fail-with-body 'https://mcp.favstash.app/mcp' \
  -H "Authorization: Bearer $FAVSTASH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_stash_summary","arguments":{}}}'
```

The JSON-RPC response must have a result without `isError: true`; zero counts are valid. Transport HTTP 200 by itself is not proof that a tool succeeded. This direct stateless API call does not test an MCP host’s initialization handshake; use the full lifecycle below to verify a connector.

## Verify a complete MCP connection

After OAuth or API-key authentication, send `initialize` with a request ID and a supported protocol version. Send `notifications/initialized` without an ID and require HTTP 202 with an empty body. Then call `tools/list` and one `get_stash_summary` with empty arguments. Send the negotiated `MCP-Protocol-Version` on subsequent HTTP requests and preserve an `Mcp-Session-Id` if the server issues one. Success requires a tool result without `isError: true`; OAuth approval, a health response, or tool discovery alone is insufficient.

Use `favstash doctor` with CLI 0.4.0+ for this sequence. It reports compatibility failures separately from rejected credentials and makes no content changes.

## Discover tool schemas

Call `tools/list` on `/mcp` with authentication, or read the [generated tool schemas](https://www.favstash.app/mcp-tools.json) and [tool reference](https://www.favstash.app/docs/tools-reference). The hosted server is authoritative at runtime. The local bridge extends media inputs with filesystem paths; those extensions are not accepted by the remote endpoint.

## REST entry points

| Method and path | Purpose |
| --- | --- |
| GET /health | Unauthenticated service health; does not verify an account |
| GET /social/channels | Connected social accounts for the authenticated owner |
| GET /social/posts | Owner-scoped content calendar |
| GET /social/entitlements | Current publishing entitlement |

The MCP tool catalogue is the complete agent-facing contract. Use it for search, save, analytics, planning, and mutations. For publishing, discover accounts and provider options first, supply a unique `clientRequestId` for idempotency, and check the returned operation status before retrying. Do not retry publishing automatically after an ambiguous network failure.

OAuth clients use discovery from the MCP origin and Authorization Code + PKCE. Third-party tokens are scoped to the signed-in owner. The ChatGPT-specific adapter at `/chatgpt/mcp` accepts OAuth only. API keys remain the fallback for automation and clients without OAuth.