# Zingu

> Zingu is an AI-curated API discovery platform. It continuously crawls, verifies, and structures metadata for hundreds of public APIs so that developers and AI agents can find and integrate the right API in seconds.

For full API documentation with examples, see [llms-full.txt](https://zingu.ai/llms-full.txt).

Zingu solves the API discovery problem: every previous API directory (ProgrammableWeb, APIs.guru, RapidAPI Hub) has stalled or died from maintenance exhaustion. Zingu automates curation with continuous crawling, live health probes, and structured metadata -- so the catalog stays fresh without manual effort.

The platform serves two audiences: human developers searching for APIs, and AI agents that need to discover, evaluate, and call APIs programmatically.

## How to Use Zingu (for AI agents)

There are several ways to use Zingu. All paths lead to the same data — pick whichever fits your environment:

1. **REST API (works everywhere, no install)** — Call the JSON endpoints below directly via HTTP. Use `GET /api/search?q=...` to find APIs, `GET /api/meta/{slug}` for endpoint details, then call the third-party API yourself using the metadata. No API key, SDK, or MCP support required — just HTTP GET requests.

2. **MCP Server (recommended for MCP-compatible clients)** — Connect to `https://zingu.ai/mcp` as a remote MCP server. Four tools: `search_apis`, `api_info`, `endpoint_info`, `call_api`. Handles discovery, metadata lookup, and API calling in a single integrated flow. Works with Claude Code, Cursor, and any MCP-compatible client.

3. **Python SDK** — `pip install git+https://github.com/zingu-ai/zingu-apis.git`. Programmatic access with automatic pagination, auth handling, and retries. Best for scripts and backend integrations.

4. **Web browsing** — Browse https://zingu.ai like a human. The site has search, topic browsing, and detailed API pages. This works but is the least efficient path — prefer options 1-3 when available.

## Recommended Workflow

Follow these steps to go from a user query to a working API call:

### Step 1: Search for APIs
Find relevant APIs by keyword. Pick the best match, or present 2-3 options to the user if ambiguous.
- MCP: `search_apis(query="weather", limit=5)`
- REST: `GET /api/search?q=weather&limit=5`

### Step 2: Inspect the API
Get the base URL, auth type, and all available endpoints with their parameters.
- MCP: `api_info(slug="openweathermap.org:current-weather-data")`
- REST: `GET /api/meta/{slug}`

### Step 3: Get endpoint details (optional)
If you need parameter details, pagination info, or examples before calling.
- MCP: `endpoint_info(slug="...", path="/weather")`
- REST: `GET /api/examples/{slug}?endpoint=GET:/weather`

### Step 4: Call the API
Call the third-party API using the metadata from steps 2-3.
- MCP: `call_api(slug="...", path="/weather", params={"q": "London"})` — handles pagination, auth, retries, and smart truncation automatically.
- Without MCP: Use the base URL and endpoint details to construct the HTTP request yourself.

**Tips:**
- Pass path parameters inside the path string: for `/{year}/data`, use `path="/2022/data"` — do not put `year` in params.
- Query parameters go in `params`: `params={"q": "Berlin", "units": "metric"}`.
- If the API requires auth, pass `key` in call_api or set env var `ZINGU_KEY_{SLUG}` (uppercase slug, dots/colons → underscores).

## REST API Quick Start (complete example)

Here is a full end-to-end example using only HTTP requests — no SDK or MCP needed:

```
# 1. Search for beer-related APIs
GET https://zingu.ai/api/search?q=beer

# Response (abbreviated):
# [{"slug": "amvera.io:punkapi", "name": "PunkAPI", "base_url": "https://punkapi-alxiw.amvera.io/v3/", "auth_type": "none", ...}]

# 2. Get metadata for the API
GET https://zingu.ai/api/meta/amvera.io:punkapi

# Response includes base_url and endpoints:
# {"base_url": "https://punkapi-alxiw.amvera.io/v3/", "endpoints": {"GET:/beers": {"path": "/beers", "method": "GET", ...}, ...}}

# 3. (Optional) Get example requests
GET https://zingu.ai/api/examples/amvera.io:punkapi

# 4. Call the third-party API directly using the metadata
GET https://punkapi-alxiw.amvera.io/v3/beers?abv_gt=10&per_page=5
```

All Zingu REST endpoints return JSON, require no authentication, and work from any HTTP client (curl, fetch, requests, etc.).

## MCP Server Setup

The MCP server is available in two forms:

- **Remote (no install):** `https://zingu.ai/mcp` — Streamable HTTP, works immediately with any MCP client.
- **Local (recommended for privacy):** `pip install git+https://github.com/zingu-ai/zingu-apis.git` from [github.com/zingu-ai/zingu-apis](https://github.com/zingu-ai/zingu-apis), then run `zingu-mcp` for stdio transport. API calls go directly from your machine to the target API — credentials and responses never pass through Zingu's servers.

## Configuration

- Base URL (production): https://zingu.ai
- Base URL (local development): https://localhost:5002
- Authentication: No API keys needed. Provide a valid email address via `?email=YOUR-EMAIL` once per session to get a higher rate limit. The email is optional — the API works without it.
- Rate limits: 10 req/hr (anonymous), 50 req/hr (email provided + delivered), 1000 req/hr (email confirmed). Add `?email=YOUR-EMAIL` to any request to upgrade.
- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`

## API Endpoints

- [Search APIs](https://zingu.ai/api/search?q=weather&limit=5): `GET /api/search?q={query}&limit={n}` -- Full-text search across API names, descriptions, categories, and tags. Supports `+` for required terms, `-` for exclusion. Returns slug, name, description, category, base_url, auth_type, and tags.
- [API Metadata](https://zingu.ai/api/meta/dayinhistory.dev:day-in-history-api): `GET /api/meta/{slug}` -- Returns auth type, base URL, CORS support, and per-endpoint metadata including pagination style, content type, description, and parameters. The slug comes from search results.
- [API Examples](https://zingu.ai/api/examples/dayinhistory.dev:day-in-history-api): `GET /api/examples/{slug}?endpoint={key}` -- Returns example requests for an API's endpoints. Optional `endpoint` filter (e.g. `GET:/today/events/`).
- [List Skills](https://zingu.ai/api/skills): `GET /api/skills?q={query}&sort={sort}&limit={n}` -- Browse task-oriented skills. Each skill groups endpoints across multiple APIs that accomplish the same user intent (e.g. "retrieve-bio-entry", "browse-statistical-datasets"). Returns id, name, description, confidence, endpoint_count, api_count. For task-shaped queries ("how do I do X?") this is often more direct than `/api/search`.
- [Skill Detail](https://zingu.ai/api/skills/browse-statistical-datasets): `GET /api/skills/{id}` -- Full skill detail with all implementing APIs grouped, each with their endpoints, roles, and sequence steps. One call returns the complete "which APIs can do X?" answer.
- [Platform Summary](https://zingu.ai/api/data/summary): `GET /api/data/summary` -- Catalog statistics: API counts, endpoint counts, probe stats, example coverage.
- [Health Timeseries](https://zingu.ai/api/data/health-timeseries?days=7): `GET /api/data/health-timeseries?days={n}&api_id={slug}` -- Daily success-rate timeseries. Filter by API slug or get platform-wide data.
- [Latency Timeseries](https://zingu.ai/api/data/latency-timeseries?days=7): `GET /api/data/latency-timeseries?days={n}&api_id={slug}` -- Daily latency measurements.
- [Status Distribution](https://zingu.ai/api/data/status-distribution?days=7): `GET /api/data/status-distribution?days={n}&api_id={slug}` -- HTTP status code distribution breakdown.
- [Slowest APIs](https://zingu.ai/api/data/slowest-apis?n=10&days=7): `GET /api/data/slowest-apis?n={count}&days={d}` -- Top N slowest APIs by latency.
- [Least Reliable APIs](https://zingu.ai/api/data/least-reliable?n=10&days=7): `GET /api/data/least-reliable?n={count}&days={d}` -- Top N least reliable APIs by success rate.
- [Run Example](https://zingu.ai/api/data/run-example/1): `POST /api/data/run-example/{example_id}` -- Live-execute a stored endpoint example and return the response with status, latency, headers, and body.

## Community Endpoints

- [Claim API](https://zingu.ai/api/claims): `POST /api/claims` -- Claim ownership of an API listing. Body: `{"api_id": "slug", "email": "you@example.com", "reason": "..."}`.
- [Report Issue](https://zingu.ai/api/reports): `POST /api/reports` -- Report a problem with a listing. Body: `{"api_id": "slug", "email": "you@example.com", "description": "..."}`.

## Python SDK

- [zingu-apis on GitHub](https://github.com/zingu-ai/zingu-apis): `pip install git+https://github.com/zingu-ai/zingu-apis.git` -- Smart client with automatic pagination, auth handling, retries, and analytics.
- [SDK Quick Start](https://zingu.ai/sdk): `zingu_apis.search("weather")` to search, `zingu_apis.api("slug")` for a metadata-aware client, `zingu_apis.call("slug", "/path")` for one-shot calls.

## Web Interface

- [API Catalog](https://zingu.ai/apis): Browse and search all APIs with filtering
- [Skills Index](https://zingu.ai/skills): Browse APIs by task/capability rather than by provider
- [Topic Browser](https://zingu.ai/browse): Browse APIs by topic/category
- [Health Dashboard](https://zingu.ai/health): Platform-wide health and reliability statistics
- [Tutorials](https://zingu.ai/tutorials): Getting-started guides for cataloged APIs

## Optional

- [OpenAPI Spec (YAML)](https://zingu.ai/openapi.yaml): OpenAPI 3.0.3 specification for all JSON endpoints
- [OpenAPI Spec (JSON)](https://zingu.ai/openapi.json): Same spec in JSON format