# Nodal AI Tools Directory API

Welcome to the Nodal REST & Agent API documentation. Nodal provides programmatic search, comparison, and discovery over thousands of curated AI tools.

## Base URL
- **Production**: `https://nodal.sonnev.com/api/v1`
- **Health Endpoint**: `https://nodal.sonnev.com/api/health`
- **OpenAPI 3.1.0 Spec**: `https://nodal.sonnev.com/api/openapi.json`
- **MCP Server**: `https://nodal.sonnev.com/api/mcp`

---

## Endpoints

### 1. Search and List AI Tools
`GET /api/v1/tools`

Retrieve paginated tools with full-text search and filters.

#### Query Parameters:
- `query` (string, optional): Search keyword (e.g. `midjourney`, `code assistant`, `voice`).
- `category` (string, optional): Category slug (e.g. `design`, `coding`, `productivity`, `video`, `audio`, `marketing`).
- `pricing` (string, optional): Pricing filter (`free`, `freemium`, `paid`, `free trial`, `open source`, `all`).
- `slug` (string, optional): Fetch a specific tool by exact slug (e.g. `midjourney`).
- `page` (integer, default: 1): Page number.
- `limit` (integer, default: 20, max: 100): Results per page.

#### Example Request:
```bash
curl -X GET "https://nodal.sonnev.com/api/v1/tools?query=image&pricing=freemium&limit=5"
```

#### Response:
```json
{
  "total": 42,
  "page": 1,
  "limit": 5,
  "totalPages": 9,
  "tools": [
    {
      "id": "1",
      "name": "Midjourney",
      "slug": "midjourney",
      "description": "Generate stunning AI art from text prompts...",
      "url": "https://midjourney.com",
      "category": "design",
      "pricing": "paid",
      "rating": 4.9,
      "tags": ["image", "art", "design"]
    }
  ]
}
```

---

### 2. List Categories
`GET /api/v1/categories`

Returns all available tool categories with tool counts.

#### Response:
```json
{
  "total": 12,
  "categories": [
    { "name": "productivity", "slug": "productivity", "count": 120 },
    { "name": "design", "slug": "design", "count": 85 }
  ]
}
```

---

### 3. Health Check
`GET /api/health`

Returns service operational status.

---

## Agent Integrations
- **API Catalog (RFC 9727)**: `https://nodal.sonnev.com/.well-known/api-catalog`
- **MCP Server Card (SEP-1649)**: `https://nodal.sonnev.com/.well-known/mcp/server-card.json`
- **Agent Skills Discovery (RFC v0.2.0)**: `https://nodal.sonnev.com/.well-known/agent-skills/index.json`
- **OAuth Discovery (RFC 8414)**: `https://nodal.sonnev.com/.well-known/oauth-authorization-server`
- **Auth.md**: `https://nodal.sonnev.com/auth.md`
