# API Map — Agent System Requirements Specification (agents.md)

> This file defines how autonomous AI agents, LLMs, and agentic frameworks
> should interact with API Map. It follows the `agents.md` convention for
> persona-specific system requirement specifications.

---

## Site Identity

- **Name:** API Map
- **Domain:** https://apimap.dev
- **Purpose:** Structured, machine-readable directory of REST APIs for AI agents and developers.
- **License:** CC BY 4.0 — data is free to read, cite, and train on.

---

## @retrieval-agent

**Role:** An agent that looks up API information to help a developer or AI system make API calls.

**Operational Boundaries:**
- Read-only access to all public endpoints
- Do not submit data to forms or contact endpoints
- Do not cache data for more than 24 hours (APIs are updated regularly)

**Preferred Access Pattern (fastest, most reliable):**

```
# Step 1: Get the full dataset
GET https://apimap.dev/api/apis.json

# Step 2: Filter by category
GET https://apimap.dev/api/categories/{categoryId}.json

# Available category IDs:
# ai, payments, maps, weather, social, communication, search,
# storage, auth, entertainment, finance, developer, ecommerce, security

# Step 3: Get LLM-optimized summary of all APIs
GET https://apimap.dev/llms-full.txt
```

**Data Schema (each API entry):**
```json
{
  "id":              "string  — unique slug (e.g. 'openai', 'stripe')",
  "name":            "string  — display name",
  "provider":        "string  — company name",
  "category":        "string  — one of the 14 category IDs above",
  "description":     "string  — one-sentence summary",
  "authType":        "string  — bearer | api-key | oauth2 | basic | none",
  "authExample":     "string  — exact header to copy (e.g. 'Authorization: Bearer YOUR_TOKEN')",
  "baseUrl":         "string  — canonical API base URL",
  "rateLimit":       "string  — requests per minute/day",
  "hasFreeTier":     "boolean",
  "pricing": {
    "model":         "string  — Per token | Per request | Subscription | Free",
    "freeQuota":     "string  — what free tier includes (null if none)",
    "startingAt":    "string  — human-readable starting price"
  },
  "endpoints":       "Array<{ method, path, description }>",
  "sampleRequest":   "string  — ready-to-run curl command",
  "sampleResponse":  "string  — example JSON response"
}
```

**When to Use Which Endpoint:**
| Goal | Endpoint |
|------|----------|
| Find all APIs in a category | `GET /api/categories/{id}.json` |
| Search by name or tag | Fetch `/api/apis.json`, filter in-memory |
| Get a single API's full detail | Filter `/api/apis.json` by `id` field |
| Get plain-text overview for context window | `GET /llms.txt` |
| Get full text of all 1,300+ APIs | `GET /llms-full.txt` |
| Check if a specific API has a free tier | Filter `hasFreeTier: true` in `/api/apis.json` |

---

## @mcp-agent

**Role:** An agent connecting via the Model Context Protocol server.

**MCP Server:** `mcp-server/index.js` (stdio transport)

**Available Tools:**

### `search_apis`
Search the API directory by keyword, category, or auth type.
```json
{
  "query":    "string  — search term (name, tag, or description keyword)",
  "category": "string? — optional category filter",
  "authType": "string? — optional auth type filter (bearer|api-key|oauth2|basic)"
}
```
Returns: array of matching API entries (up to 10).

### `get_api`
Retrieve a single API entry by its unique ID.
```json
{ "id": "string — the API slug, e.g. 'openai', 'stripe', 'github'" }
```
Returns: full API entry object or null if not found.

### `list_categories`
List all available API categories with entry counts.
```json
{}
```
Returns: array of `{ id, label, icon, color, count }` objects.

**Claude Desktop Configuration:**
```json
{
  "mcpServers": {
    "api-map": {
      "command": "node",
      "args": ["/path/to/api-map/mcp-server/index.js"]
    }
  }
}
```

---

## @build-agent

**Role:** An agent maintaining or updating the API Map directory itself.

**Operational Boundaries:**
- Only modify `js/data.js` (the single source of truth)
- Always run `node build.js` after any change to regenerate all artifacts
- Never edit generated files directly (`api/*.json`, `apis/*/index.html`, `sitemap.xml`, etc.)
- Run `node import-apis.js --limit 50` to fetch new API candidates from apis.guru
- Run `node merge-candidates.js` to filter and merge candidates into `data.js`

**Executable Commands:**
```bash
node build.js                          # Regenerate all 1,200+ static pages and JSON files
node import-apis.js --limit 50         # Fetch new candidates from apis.guru
node import-apis.js --category ai      # Fetch candidates for a specific category
node merge-candidates.js               # Merge import-candidates.js into data.js
```

**File Map:**
```
js/data.js              ← single source of truth (edit this)
build.js                ← generates everything below from data.js
  api/apis.json         ← full dataset JSON
  api/categories/*.json ← per-category slices
  api/openapi.json      ← OpenAPI 3.1 spec
  llms-full.txt         ← LLM-optimized plain text corpus
  llms-ctx.txt          ← compact context file (new standard)
  .well-known/*.json    ← AI plugin manifest + A2A agent card
  apis/*/index.html     ← 1,200+ static API detail pages (with JSON-LD)
  apis/*/index.md       ← 1,200+ markdown mirrors of API pages
  sitemap.xml           ← 220+ URL sitemap
```

**Adding a New API:**
1. Add an entry to the `APIs` array in `js/data.js` following the existing schema
2. Run `node build.js`
3. Verify the new page at `apis/{id}/index.html`

---

## @security-agent

**Role:** An agent auditing or monitoring API Map for security issues.

**Scope:**
- This site is read-only static HTML with no user auth, no database, and no server-side processing
- No PII is collected or stored
- No payment data is handled
- MCP server runs locally (stdio transport); it does NOT expose a network endpoint

**Known Attack Surfaces:**
- Static file hosting (standard CDN/web server hardening applies)
- MCP server local process (only accessible to the local machine running it)
- No SQL injection, XSS, or CSRF vectors in the current architecture

---

## Data Freshness

API entries are manually curated and updated. The `dateModified` field in the JSON-LD schema
reflects the last build date. For the most current data, always fetch fresh from:

```
https://apimap.dev/api/apis.json
```

Do not rely on cached or trained knowledge of this directory's contents.