# Pulrix API Documentation

Base URL: `https://pulrix.dev/api/v1`

## Authentication

- **Free tier:** 10 queries/day by IP. No auth needed.
- **Authenticated:** Unlimited queries. Pass your API key as a Bearer token:

```
Authorization: Bearer plx_your_api_key_here
```

## Rate Limiting

Anonymous requests include these headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Max requests per window |
| `X-RateLimit-Remaining` | Requests remaining |
| `X-RateLimit-Reset` | Unix timestamp when window resets |

Returns `429` when exceeded.

---

## Endpoints

### GET /api/v1/search

Search for MCP servers by keyword.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | Yes | Search query (max 200 chars) |
| `grade` | string | No | Filter by grade (A+, A, B, C, D, F) |
| `limit` | number | No | Results per page (default 20, max 50) |
| `offset` | number | No | Pagination offset (default 0) |

**Example:**

```bash
curl "https://pulrix.dev/api/v1/search?q=postgres&limit=5"
```

**Response:**

```json
{
  "query": "postgres",
  "count": 5,
  "total": 5,
  "limit": 5,
  "offset": 0,
  "servers": [
    {
      "id": "crystaldba/postgres-mcp",
      "name": "postgres-mcp",
      "grade": "A",
      "score": 82,
      "description": "All-in-one MCP server for PostgreSQL",
      "repo_url": "https://github.com/crystaldba/postgres-mcp",
      "last_scored": "2026-03-20T14:30:00.000Z"
    }
  ]
}
```

---

### GET /api/v1/servers/:id

Get detailed information about a specific server, including full score breakdown and history.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Server ID (URL path parameter) |

**Example:**

```bash
curl "https://pulrix.dev/api/v1/servers/crystaldba%2Fpostgres-mcp"
```

**Response:**

```json
{
  "server": {
    "id": "crystaldba/postgres-mcp",
    "name": "postgres-mcp",
    "description": "All-in-one MCP server for PostgreSQL",
    "repo_url": "https://github.com/crystaldba/postgres-mcp",
    "npm_package": "@crystaldba/postgres-mcp",
    "source": "awesome-list",
    "first_seen": "2026-03-01T00:00:00.000Z"
  },
  "score": {
    "grade": "A",
    "total": 82,
    "scored_at": "2026-03-20T14:30:00.000Z",
    "quality": {
      "signals": {
        "schema_valid": { "points": 15, "max": 15 },
        "readme": { "points": 6, "max": 6 },
        "tests": { "points": 6, "max": 6 },
        "typescript": { "points": 6, "max": 6 },
        "license": { "points": 3, "max": 3 },
        "stars": { "points": 5, "max": 6 },
        "activity": { "points": 10, "max": 10 },
        "issues": { "points": 3, "max": 3 },
        "cves": { "points": 5, "max": 5 }
      }
    },
    "security": {
      "score": 40,
      "max": 40,
      "findings_count": 0,
      "vendors": {
        "virustotal": { "malicious": 0, "total_engines": 72 },
        "osv": { "total_vulns": 0 },
        "github_advisories": { "total": 0 }
      }
    }
  },
  "history": [
    { "grade": "A", "total": 82, "scored_at": "2026-03-20T..." },
    { "grade": "B", "total": 78, "scored_at": "2026-03-13T..." }
  ]
}
```

---

### GET /api/v1/top

Get top-scoring MCP servers, optionally filtered by category or grade.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Filter by category keyword (default: all) |
| `grade` | string | No | Filter by minimum grade |
| `limit` | number | No | Results to return (default 25, max 50) |

**Example:**

```bash
curl "https://pulrix.dev/api/v1/top?grade=A&limit=10"
```

**Response:**

```json
{
  "category": "all",
  "count": 10,
  "servers": [
    {
      "id": "modelcontextprotocol/servers",
      "name": "servers",
      "grade": "A+",
      "score": 94,
      "description": "Official MCP reference servers",
      "repo_url": "https://github.com/modelcontextprotocol/servers",
      "last_scored": "2026-03-20T14:30:00.000Z"
    }
  ]
}
```

---

### GET /api/v1/compare

Compare up to 5 servers side by side. Returns a recommendation for the best option.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ids` | string | Yes | Comma-separated server IDs (max 5) |

**Example:**

```bash
curl "https://pulrix.dev/api/v1/compare?ids=server-a,server-b,server-c"
```

**Response:**

```json
{
  "servers": [
    { "id": "server-a", "name": "Server A", "grade": "A", "score": 85 },
    { "id": "server-b", "name": "Server B", "grade": "B", "score": 72 },
    { "id": "server-c", "name": "Server C", "grade": null, "score": null, "error": "Not found" }
  ],
  "recommendation": "server-a",
  "reason": "Highest composite score (85/100, grade A)"
}
```

---

### GET /api/v1/stats

Get aggregate statistics about the Pulrix index.

**Example:**

```bash
curl "https://pulrix.dev/api/v1/stats"
```

**Response:**

```json
{
  "total_servers": 17432,
  "scored_servers": 14891,
  "grade_distribution": {
    "A+": 142, "A": 891, "B": 2341,
    "C": 4521, "D": 3102, "F": 3894
  },
  "last_crawl": null,
  "last_score_run": null
}
```

---

### POST /api/v1/check

Request an on-demand security check for a specific MCP server. **Requires API key.** Coming in v0.2.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | GitHub repo URL or npm package name |

**Example:**

```bash
curl -X POST "https://pulrix.dev/api/v1/check" \
  -H "Authorization: Bearer plx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo"}'
```

---

## CLI

The Pulrix CLI wraps the API. No installation required.

```bash
# Search for servers
npx pulrix search "postgres"

# Get server details
npx pulrix info github:owner/repo

# Compare servers
npx pulrix compare server-a server-b
```

Set `PULRIX_API_KEY` environment variable for unlimited queries.

## MCP Server

Let your AI agent search for and evaluate its own tools.

```json
{
  "mcpServers": {
    "pulrix": {
      "command": "npx",
      "args": ["-y", "pulrix", "mcp"]
    }
  }
}
```

Add your API key via `PULRIX_API_KEY` env var for unlimited queries.

## Error Codes

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Bad request (missing or invalid parameters) |
| 401 | Unauthorized (API key required) |
| 404 | Server not found |
| 429 | Rate limit exceeded |
| 500 | Server error |
| 501 | Not implemented |

---

Questions? Open an issue on [GitHub](https://github.com/slape/pulrix) or email hello@pulrix.dev.